In my last post I promised to tell you more about the performance counters. So here we are: today I'm going to tell you about how to use the performance counter infrastructure offered by Windows in a .net application. On top of this I'm providing you with a basic framework that you can use to author performance counters through XML and then get the code to read/write the counters generated for you at build time. So let's get started.

Some Basics

Before I go off to the code, here's a little overview on performance counters in Windows. I'm sure if you're reading this, you already know about Perfmon.exe, a nice little tool to look at various performance aspects of Windows machines. When plottig performance counters, you're typically adding the counters you're interested in. These counters are grouped in categories, for instance Processor or PhsyicalDisk. Each category can contain multiple counters, for instance Disk Read Bytes/sec or Disk Write Bytes/sec. And finally, each counter can have multiple instances, for instance in multi-processor machines, you'll find one instance of the % Idle Time counter per processor.

What tools like Perfmon.exe do is to grab the values of the counters you selected every second (by default, but that can typically be changed) and record/plot the values. Your job here is to build performance counters that measure certain aspects of your application so these tools can help you in analyzing your performance. And that's why you're here, right?

Step 1: The XML Schema

In order to know what we talk about in the XML I announced, let me start with the XML schema. I use this mainly to make sure that what I have in the XML declaring the perf counters makes some sense and is legal input. And of course because Visual Studio tells you that something's wrong when the schema is not adhered to.

On lines 21 to 23 you find some enumeration values. These map to the values defined in the PerformanceCounterType Enumeration. This is also where you can add support for more performance counter types when you need it. The other elements and attributes are used to describe the category for the performance counters and the performance counters themselves, including the help text that will show up in Perfmon.exe and also including the symbol that you can use in the code to access the counter.

Step 2: Declaring the Performance Counters

Now let's use the schema we built above. To give you an idea of the context, I'm providing here some of the XML I use to build the perf counters for my SMTP server.

As you can see, I create seven perf counters, most of them ordinary counters that count the number of occurrences of a certain event (like when a client makes a connection to the server). I actually also use the NumberOfItems32 type to count the number of active connections — I basically increment the counter when a connection was established and decrement it when the connection is terminated. And I have a couple of counters which count the number of occurrences per second (the RateOfCountsPerSecond32 counter type). The good thing about these counters is that you don't need to provide your own counter base (check out MSDN for more info on this, starting with the above mentioned PerformanceCounterType Enumeration).

Step 3: Building the XSLT to Generate Code

We already have our perf counters declared, so let's generate some code from that XML. Using XSL stylesheets makes this very easy: We'll use the XML as input and get c# code as output that we can simply include into our project. I won't show the full XSLT here (it's about 240 lines).

On lines 9 to 11 you'll find the declaration for the parameters which you can use to change the namespace, the class name and the access modifiers (public vs internal really) for the generated classes.

Starting on lines 22 and 37 respectively, you find different templates for general counters and the RawFraction type counters. I use this to automatically generate the base counter so you won't have to worry about it. You can do similar things for other counters which need a base counter. Then, starting on lines 63 and 72 respecctively, I initialize the counters, with specialization again for the RawFraction counter types. And starting on lines 86 and 100 respectively you'll find the code to create and set the CounterCreationData which is used to register perf counters.

You can find the full code in the ZIP file linked to at the end of this post. With this we basically have all the tools we need to actually generate the code as part of the build. We just need to bring the pieces together.

Step 4: Bringing it Together aka Updating the Project

Well yes, I have silently assumed that you have a c# project (.csproj or any other project that is supported by MSBuild.exe) that you're working on to update. All we need to do in the .csproj is to add the files we authored, then run the XSLT transformation and add the output .cs file to the list of source code files as well. And here's how you can do that.

Add lines 4 to 32 to the end of the project file and make sure the paths you're using point to the places where you actually stored the files. On line 8 you can see that I'm passing the target namespace parameter (called out in step 3) by concatenating the assemblies default root namespace and ".Diag". This way you can actually put this stuff into a .targets file that you can include in all of the projects which take advantage of this framework.

Starting on line 25 I defined the actual target which runs the XslTransformation task that comes with .net 4.0. I also declared the inputs as being the XML file and the XSLT file — this way, while experimenting with the XSLT, the code gets regenerated also if the XML file hasn't changed, but the XSLT has.

Using the Generated Classes

So now you have pretty much all the code you need to use these performance counters of yours. All that's left is actually writing the code which

1. Installs the Performance Counters
2. Updates the Performance Counters
3. Uninstalls the Performance Counters

#1 and #3 would probably be used by your installer and #2 by your application at runtime. Incrementing and decrementing the counters is as easy as

Where PerfCounters is the name of the generated class which contains all the generated perf counters, CymbeMail is the name of the class for the category (the Symbol attribute, remember?) and ActiveConnections is of course the symbol name for the counter we're modifying. Isn't this simple?

As for setting things up (or removing them), the relevant piece of code gets generated for you, too. So all you need to do is actually call it, potentially from a small application that you run — as I mentioned before — from your installer.

Of course you'll have to make sure that the version of the generated code that's run by the uninstaller is the same version as the installer did run — else you may end up with stale categories / counters on the machine. But then again, if you're installing through an MSI package, you get that for free ... when done properly.

Summary

In just a few steps I have shown how you can build a framework to use performance counters in .Net applications. On top of it's simplicity, it's also quite easy to modify the framework and adapt it to your own needs or extend it to allow more performance counter types.

And finally, as promised, here's the ZIP file which contains the relevant pieces. Please forgive me for not adding the .csproj file — that actually contains other relevant data that I didn't want to share. Instead I added the generated c# code file for reference.

PerfCounters.zip (4.08 kb)

I have updated my mail server code to report some very basic diagnostics data through performance counters (I'll come back to that in a future post). Amongst the information that's being logged are:

• The total number of connections since the server was started.
• The total number of connections refused (due to server and anti-spam policies) since the server was started.

I've looked at these numbers after a couple of hours of the server being online. There were about 60K connections, out of which a bit more than 75% have been refused SMTP transactions because the remote hosts were identified as spam senders.

... the other day. It contained lots of material for me to read through and a form to fill in. But that's not the reason why I'm typing this.

In order to still participate in certain elections and votes back in Switzerland, I have to register with the Swiss consulate in San Francisco. After doing so, they sent me a letter with additional info and forms. What I find most intriguing is that, even though they're based in the US, they must have had their paper and envelopes shipped from Switzerland.

This is surely no surprise for many people: you can actually debug managed code with WinDbg (or CDB, if you prefer that one) by using the SOS extension (that ships with the .Net framework) in the debugger. What's new is that today, Microsoft released Psscor2 which is pretty much an enhanced version of SOS. Now I'm sure that you'll soon find much information on using Psscor2 on Tom's blog. I'm much in favor of Psscor2 myself and therefore I'll try to post useful scripts here as well (if I can come up with some ;-)).

I decided to start with a new series of posts (oh well, I guess it'll turn out later if it's really going to be a series) of Here's to ... Xyz posts to praise (or slam; go figure it out!) stuff.

So here's to changes. If someone told me a year ago where I would be in a year and what I would be doing, I would have smiled at them and thought something like 'Yeah, whatever.' But here I am: After almost 4 years in Microsoft's Development Center in Zurich, Switzerland I decided to pursue new opportunities and to move to Redmond in the state of Washington, where I am now working as part of the Windows Services and Content team in the Windows client organization. Which gets me right to the point: Changes. For me this really was a big change and so far I think it was well worth it. I have to admit though, that I did underestimate the work and stress invovled in the relocation (and I'm not completely done yet). On the other hand, what I gained so far already is priceless. So maybe in a year from now, you should ask me what I think about this. And maybe I'll still tell you the same thing. Changes can be a good thing, if you give it a try.

... in order to pick up the changes you've recently made to the environment variables.

Alright, to cut a long story short, I'm using the Microsoft Natural Ergonomic Keyboard at work. It has these (5) 'My Favorits' keys on top to which you can assign custom commands. I typically make heavy use of that to

1. Start a new console for the build environment
2. Start PowerShell
3. Start a lightweight editor with syntax hightlighting for many file types
4. Start PaintDotNet
5. Start a new (blank) console

I typically use #5 for checking out small things and starting remote user debugging sessions. From time to time, I tweak the environment a little bit by adding new environment variables or modifying existing ones (like e.g. adding new places to the %PATH% environment variable). To verify, I use the command line. Except that existing processes don't automatically get the new variables. I was recently tricked by this, since I pressed #5 to get a new console and test the changes. Nothing there. Hmmm. When I start %COMSPEC% they are there. So why not with #5?

Well, the process which starts #5 was started when the changes to the environment variables where not yet made. That's why also the processes started from this process don't have the changes. So all I've got to do in this case is to kill itype.exe and then start it right away again. Now it works!

Tracing OCS components may be vital in troubleshooting various issues you may face in your deployment. On machines where you have OCS components installed, you'll typically find a tool called OCSLogger.exe which allows you to start/stop/view traces of OCS components. However, sometimes this is not enough, for instance when you see problems at the startup of a machine. It's kind of hard to run the GUI if you cannot logon yet. But you can typically run a scheduled task. Or maybe you are — just like me — more like the console guy and thus want to have a script/cmdline tool for everything.

Let's start with the config file used by the script (TraceConfig.xml) which defines the components you want to trace, to what level the traces are supposed to be and some more things. The sample given here traces mostly the components which are useful in troubleshooting issues related to the Response Group Service of OCS.

I added the most importan trace levels and flags in the comment. Right now, the Default element defines the levels and flags for all components, but there's no reason why you shouldn't be able to do that per component you want to trace.

The PS1 script itself (Tracer.ps1) heavily relies on the OcsTracer.exe tool which also comes with OCS and is typically installed in the same place as OcsLogger.exe. It has four main actions:

1. Start tracing components
2. Stop tracing components and format the traces
3. Format traces of ETL files (e.g. from a different machine)
4. Show the configuration details from a particular config XML file

For samples on how to run the script, please run man .\Tracer.ps1 -Examples Have fun :)

At work, I have created multiple tools which we used to analyse and fix issues related to certificates that we use with Office Communications Server and their respective private key files. To summarize, a user/service who wants to use the certificate for authentication needs to have read access on the private key. If it doesn't, you'll typically see a strange error which many people don't relate to missing ACLs on the private key file.

Now these days, you don't need to write such tools anymore. PowerShell allows you to pretty much do everything you need in this area. Let's look at the following PS script (let's call it FindPrivateKey.ps1) which accepts a parameter of type System.Security.Cryptography.X509Certificates.X509Certificate2, i.e. a reference to the certificate you want to analyze.

I guess I do not need to mention that you can easily find the certificate you're interested in by running something like

where '0DAC31905AEB722D8561BFAF3F3BFD2F551AA197' is simply the thumbprint of the certificate we're interested in. From here on it should be easy to check what ACLs the file has (run $file.GetAccessControl()) and to modify them (run $file.SetAccessControl()).