Table of Contents:

1.0 Introduction - Description and Purpose
1.1 Prerequisites
1.2 Limitations
1.3 Install BtM for .NET Toolkit
2.0 Instrument C# and VB.NET Applications
2.1 Make the BtM Toolkit Available
2.2 BtM Toolkit Explorer
2.2.1 Open BtM Toolkit Explorer
2.2.2 BtM Toolkit Explorer Help
2.2.3 Create New Profile
2.2.4 Configure Profile
2.2.5 Launch Profile
2.2.6 View Reports
2.3 BtM Source Editing
2.3.1 CBE Instrumentation using Source Editing
2.3.2 ARM Instrumentation using Source Editing
2.3.3 Deletion of instrumented codes
2.3.4 Comparison between BtM Explorer Report and Souce Editing Report
3.0 Real Case Example: Instrument Microsoft PetShop by BtM .NET Toolkit
3.1 Preparing Operations
3.2 Instrument PetShop with ARM
3.3 Instrument PetShop with CBE
4.0 Deployment
5.0 Walk Smoothly Among Various Postsharp Versions
5.1 Configuration by Adding .config xml File
5.2 Configuration by Microsoft Manangement Console

The Build-to-Manage (BtM) Toolkit for .NET is an add-in for Visual Studio 2005. It promotes a set of monitoring and event standards that have been available for Java programmers for some time. This document describes how to use these management standards to help instrument user code for response time measurement, event creation, and event correlation.

• Application Response Measurement (ARM): Created by the Computer Measurement Group and now standardized by The Open Group, ARM measures application availability and performance. It collects response times and application-detected errors, with sampling to lower data collection overhead. ARM uses a correlator to track transactions across disparate systems.
• Common Base Events (CBE): An IBM initiative that defines a common XML schema for logging and events, CBE allows autonomic systems to evaluate disparate sources of system information before taking action.

The current BtM add-in supports Visual Studio.NET 2005 and .NET Framework 2.0 and 3.0. If you are using this version of the add-in and install any beta Visual Studio software on your machine, including a beta .NET Framework, you may not be able to use the add-in to access workspaces.

• Visual Studio 2005
• Microsoft .NET Framework 2.0 (by default, it is shipped with Visual Studio 2005) or Microsoft .NET Framework 3.0
• PostSharp 1.0 Beta Release (version 1.0.5.196)       PostSharp

The list below indicates some of the known limitations for the BtM .NET Toolkit.

• Cannot instrument an application with many embedded try-catch clauses.
• PostSharp cannot be used on projects signed with a strong name.

Manual Installation

Invoke ManualInstall.bat from command line with one parameter: the target folder for the installation.

The BtM for .NET Toolkit is integrated into Visual Studio as an add-in. All C# and VB.NET applications can be instrumented with the BTMToolkit selection from the Tools menu. There are two mechanisms to instrument C# or VB.NET applications using the BtM for .NET Toolkit: the BtM Toolkit Explorer uses PostSharp to add instrumentation; BtM source editing adds instrumentation calls to the application source code.

After installation, BtM for .NET Toolkit is integrated into Visual Studio; however, you will need to make it available with the Add-in Manager. This is a one-time operation.

1. On the Tools menu click Add-in Manager…
2. Check the 'BTMAddin' selection to make it available
3. The BtM Toolkit Explorer will open and 'BTMToolkit' will be added to the 'Tools' menu

The next time Visual Studio is started, the BtM add-in will already be available; the 'BTMToolkit' entry will appear on the 'Tools' menu.

The BtM Toolkit Explorer uses PostSharp to instrument C# and VB.NET applications in Visual Studio.

1. In Visual Studio click Tools -> BTMToolkit to open the BtM Toolkit Explorer.


Figure 1 - Open BtM Toolkit Explorer


2. The BtM Toolkit Explorer will pop up.


Figure 2 - BtM Toolkit Explorer


Note: When you open the BtM Toolkit Explorer without opening any solution, all of the buttons on the BtM Toolkit Explorer will be disabled .

Click the help icon on the BtMToolkit Explorer. Help information for the BtM Toolkit will be displayed.

You can also click on Help -> Contents to see help information for the BtM Toolkit.

To create a new profile for your application, you can either click the Create New Profile button or the New Profile Wizard button on the BtM Toolkit Explorer.

Configure a profile either by double-clicking the solution in the profile you created or by using the 'New Profile Wizard'.

Example 1: CBE Instrumentation

1. After clicking the 'New Profile Wizard', the general configuration welcome page will pop up and you can specify the custom profile name here. Click Next.
2. 'Select Instrument Type' dialogue will pop up. Check ‘Common Base Event Analysis’ box. Click Next.
3. 'Select Filters' dialogue will be shown. By default, the Namespace frame is the active project namespace, with default values provided by the BtM Toolkit Explorer. There are two kinds of rules: Include and Exclude. Include is the default value. Enter the class and method name that you want to instrument; or enter the wildcard '*' to instrument all classes/methods.
4. Click the Finish button to complete the profile.


Figure 3 - General Configuration


Figure 4 - CBE Instrumentation


Figure 5 - Filter Configuration

Example 2: Eclipse TPTP ARM Implementation

1. After clicking the 'New Profile Wizard' a 'Select Instrument Type' dialogue will pop up. Check ‘Application Response Measurement Analyses’ box, and the ‘Edit Options’ button will be enabled. Click this button to configure your ARM implementation.
2. Select ‘Eclipse TPTP ARM Implementation’ in the pop up dialogue. Click OK. And return to 'Select Instrument Type' dialogue, click Next.
3. Select Filters dialogue will be shown. By default, the Namespace frame is the active project namespace, with default values provided by the BtM Toolkit Explorer. There are two kinds of rules: Include and Exclude. Include is the default value. Enter the class and method name that you want to instrument; or enter the wildcard '*' to instrument all classes/methods.
4. Click the Finish button to complete the profile.


Figure 6 - ARM Instrumentation Configuration


Figure 7 - Eclipse TPTP ARM Instrumentation Configuration

Launch the profile by:

• Right-click an existing profile and click Launch With Profile
• Choose the profile you would like to launch from the menu bar and click the Launch With Profile button

CBE Report

After launching the profile instrumented for CBE, a CBE report will appear just below the Reports folder of the profile.

Figure 8 - CBE Report

Eclipse TPTP ARM Report

After launching the profile instrumented by Eclipse TPTP ARM, an Eclipse TPTP ARM report will appear just below the Reports folder of the profile.

Figure 9 - Eclipse TPTP ARM Report

Using BtM source editing is an alternative means to instrument C# and VB.NET applications in Visual Studio. To invoke BtM source editing, right-click in the code region and the 'Insert BtM Code' option will be displayed in the menu list.

Figure 10 - Source Editor Menu

Method Level Instrumentation

1. Place the cursor in the method you want to instrument with BtM source editing.
2. Click 'Instrumenting BtM Code' -> 'Insert CBE code'.
3. BtM instrumentation for CBE will be added to the entry and exit point of the selected method.
4. Run your project. If you choose 'Start Debugging', then the CBE log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the CBE log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.
   

Class Level Instrumentation

1. Place the cursor in the class you want to instrument with BtM source editing.
2. Click 'Instrumenting BtM Code' -> 'Insert CBE code'.
3. BtM instrumentation for CBE will be added to the entry and exit point of all methods in the selected class.
4. Run your project. If you choose 'Start Debugging', then the CBE log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the CBE log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.
   

Solution Level Instrumentation

1. Place the cursor in the solution.
2. Click 'Instrumenting BtM Code' -> 'Insert CBE code'.
3. BtM instrumentation for CBE will be added to the entry and exit point of all methods in the solution.
4. Run your project. If you choose 'Start Debugging', then the CBE log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the CBE log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.
   

Note: The priority level of the above three kinds of instrumentation is: Method Level > Class Level > Solution Level . So if you want to instrument a whole class, you have to place the cursor in the class domain but not any of the specific method inside the class.

Method Level Instrumentation

1. Right Click in the method you want to instrument with BtM source editing.
2. Click 'Instrumenting BtM Code' -> 'Insert ARM code'.
3. Select Eclipse TPTP ARM Implementation in the checklist box.
4. Click the OK button.
5. BtM instrumentation for ARM will be added to the entry and exit point of the selected method.
6. Run your project. If you choose 'Start Debugging', then the ARM log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the ARM log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.

Figure 11 - Source Editing Eclipse TPTP ARM Configuration

Class Level Instrumentation

1. Right Click in the Class you want to instrument with BtM source editing.
2. Click 'Instrumenting BtM Code' -> 'Insert ARM code'.
3. Select Eclipse TPTP ARM Implementation in the checklist box.
4. Click the OK button.
5. BtM instrumentation for ARM will be added to the entry and exit point of all methods in the selected class.
6. Run your project. If you choose 'Start Debugging', then the ARM log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the ARM log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.

Solution Level Instrumentation

1. Right Click in your solution.
2. Click 'Instrumenting BtM Code' -> 'Insert ARM code'.
3. Select Eclipse TPTP ARM Implementation in the checklist box.
4. Click the OK button.
5. BtM instrumentation for ARM will be added to the entry and exit point of all methods in the solution.
6. Run your project. If you choose 'Start Debugging', then the ARM log file will be created in the %ProjectDir%\bin\Debug folder. If you choose 'Start Without Debugging', then the ARM log file will be in the %ProjectDir%\bin\Release folder. Note: Here, %ProjectDir% represents the location of your project.

Note: The priority level of the above three kinds of instrumentation is: Method Level > Class Level > Solution Level . So if you want to instrument a whole class, you have to place the cursor in the class domain but not any of the specific method inside the class.

Method Level Deletion

1. Right Click in the method you want to delete BtM instrumentation codes.
2. Click 'Instrumenting BtM Code' -> 'Delete instrumented code of current method'.
3. Any BtM instrumentation of the selected method will be deleted.


Figure 12 - Method Level Deletion

Class Level Deletion

1. Right Click in the class you want to delete BtM instrumentation codes.
2. Click 'Instrumenting BtM Code' -> 'Delete instrumented code of current class'.
3. Any BtM instrumentation of the selected class will be deleted.


Figure 13 - Class Level Deletion

Solution Level Deletion

1. Right click in your solution.
2. Click 'Instrumenting BtM Code' -> 'Delete all instrumented codes'.
3. All BtM instrumentation will be deleted.


Figure 14 - Solution Level Deletion

If you instrument the same application from BtM Explorer and Source Editor and view the two arm reports from BtM Explorer, you will find that there are minor differences between them. This is because:

1. BtM Explorer can not instrument constructor method while Source Editor can.
2. BtM Explorer can instrument c# property while Source Editor can not.
3. If a class doesn't contain parameterless constructor, .NET framework will add a .ctor method (default constructor) for it. BtM Explorer report can reflect this .ctor method while Source Editor can not

Here are the sample reports, you can draw the difference there:
Figure 15 - BtM Explorer ARM Report

Figure 16 - BtM Source Editing ARM Report

3.0 Real Case Example: Instrument Microsoft PetShop by BtM .NET Toolkit

Microsoft Petshop is an online shop which sells various kinds of pets. Clients can choose and select the pets they like, and provide a credit card to pay, as well as their shipping address. In this section, we will use BtM for .NET Toolkit to instrument MS PetShop step by step.

Figure 17 - Petshop

Two versions of Petshop are available at:

• PetShop 2.0 used for ARM.
• PetShop 4.0 used for CBE

Before instrumenting MS Petshop, you need to :

1. Remove Strong Name from PetShop Projects. This is because BtM for .NET Toolkit doesn't support strong name while in default MS PetShop projects are shipped with strong name.

The following is a simple guide about how to remove PetShop strong name in Visual Studio. I'll choose BLL project as an example:

1. Right-Click on the BLL project and click Properties.

Figure 18 - Strong Name Property

2. Choose Signing tag in the Properties window. By default, the tag 'Sign the assembly'is chosen.

Figure 19 - Strong Name Property

3. Remove the selection and save your modification.

Figure 20 - Strong Name Property

4. Repeat the above operations to remove strong name of all projects under PetShop solution, and rebuild the solution.
2. Change the security property of BtM report folder. Since by default, if you instrument a project using BtM .NET Explorer, the ARM/CBE report file will be created in the folder of .sln file; and if you instrument the project by BtM .NET Source Editing, the ARM/CBE report file will be created in the output folder of your project. So you have to make sure that you have full access property of such report folders to create the BtM report files whenever you are in the development scenario or in the product scenario when deploying. In the case of PetShop, you have to grant the full Control right of the PetShop Installation folder , in default, it's "C:\Program Files\ Microsoft " , to 'Users' as followed.

   
   Figure 21 - Changing Security Property of BtM .NET Report Folder

The Petshop 2.0 solution as two parts: Components and Web. The Web part includes the ASP.NET page design--the presentation. The Components part supports the business logic.

1. We will instrument key operations (methods) before deploying the Petshop. In this case, we choose to instrument the following functions:
   • Account.cs: SignIn()
   • Cart.cs: Add(), Remove(), GetItems(), GetTotal()
   • CartItem.cs: Refresh()
   • Item.cs: GetItemsByProduct(), GetItem()
   • Product.cs: GetProductsByCategory(), GetProductsBySearch()
   These will be instrument with Eclipse TPTP ARM Instrumentation using BtM source editing. For example, the instrumented SignIn() function looks like this:
   

   
   Figure 22 - Petshop ARM Instrumentation Sample
   
   Note: Remember to record your designated ARM report location.

2. Rebuild and publish the Petshop Web Site which references the components already instrumented with Eclipse TPTP ARM.
3. Visit Petshop from a web browser.
4. Check the ARM report to view the resulting performance records.
5. Using the BtM Toolkit Explorer, the ARM report would like this:
   
   Figure 23 - Eclipse TPTP ARM Report
   
   

The Petshop 4.0 solution is divided into three layers: presentation layer, business logic layer and database layer.

1. We will monitor the performance of the client purchasing process; so we choose to instrument key functions from all layers.
   • .\DBUtility\SQLHelper.cs: ExecuteReader(),GetCachedParameters(),PrepareCommand()
   • .\Profile\PetShopProfileProvider.cs: Initialize(), GetPropertyValues(), SetPropertyValues(),GetAccountInfo(),SetAccountInfo(),SetCartItems(), FindProfilesByUserName(),GetAllProfiles()
   • .\ SQLProfileDAL\PetShopProfileProvider.cs.: GetAccountInfo(),SetAccountInfo(), GetCartItems(),SetCartItems(),CreateProfileForUser(),DeleteProfile(), GetProfileInfo()
   • .\ SQLServer\Category.cs: GetCategories(), GetCategory()
   • .\ SQLServer\Inventory.cs: CurrentQtyInStock(),TakeStock(), GetInventoryParameters()
   • .\ SQLServer\Item.cs: GetItemsByProduct(),GetItem()
   • .\ SQLServer\Order.cs: Insert(),GetOrder()
   • .\OrderProcessor\Program.cs: Main(), ProcessOrders()
   • .\BLL\Cart.cs: Add(), Remove(),? GetOrderLineItems(),Clear()
   • .\BLL\Category.cs: GetCategory()
   • .\BLL\Inventory.cs: CurrentQuantityInStock()
   • .\BLL\Item.cs: GetItemsByProduct(),GetItem()
   • .\BLL\Order.cs: Insert(),ProcessCreditCard(),GetOrder()
   We instrument these methods with CBE Instrumentation with BtM source editing. As an example, the instrumented Cart.cs: Add() function looks like this:
   

   
   Figure 24 - Petshop CBE Instrumention Sample

2. Rebuild the Petshop solution and visit the Petshop default website.
3. Check the CBE report to view the resulting event records.
4. Using the BtM Toolkit Explorer, the CBE report would look like this:
   
   Figure 25 - CBE Report
   
   

In development, if you monitor your application using our BtM for .NET toolkit, then the required BtM dlls will be copied to your application output folder automatically. When you deploy your already instrumented application to another machine, all you have to do is to deploy the BtM dlls together with your application output exe or dll files into the same folder on your target machine.

The required BtM dlls include:

1. BTMInstrumentManager.dll
2. libcbe101net.dll
3. ARMInterface.dll
4. In development scenario, we use ARMEngine.dll to perform ARM monitoring. However, in product scenario, we sincerely recommend you to use a production .NET ARM library for this purpose, for example, the .NET ARM library which is provided by ITCAM for Response Time (RT) product.

Up to now, you are quite familiar with our BtM Toolkit for .NET, and can use it well at ease. But what if one day you find that Postsharp upgrades to a higher version? Surely you would like to install the latest version, but can BtM Toolkit for .NET which referenced the previous version of Postsharp work fine? The answer is yes, as long as the Postsharp API has not been changed and you would do very few manual configurations as follow.

In total, there are two methods to configure, one is through Microsoft Manangement Console and the other is by adding xml configuration file.

1. Development Scenario

   In development, after you have installed our BtM .NET Toolkit, two configuration files named BTMAttribute.dll.config and BTMWeaver.dll.config will be installed in the BtM .NET Toolkit installation folder by default. The two files are all xml files.

   BTMAttribute.dll.config file only contains the configuration for PostSharp.Public.dll, so you just have to change the 'newVersion' attribute of tag <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="1.0.5.192" /> into the newly releasd version of Postsharp you have installed. For example, if one day Postsharp released a version 1.0.9.100 and you installed this version in your computer, all you have to do to configure the BtM .NET Toolkit you previously installed is to change the above tag to <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="1.0.9.100" /> .

   The same modification is also true for BTMWeaver.dll.config except that BTMWeaver.dll.config not only contains configuration for PostSharp.Public.dll but also for PostSharp.Core.dll. So in this file, you not only have to modify the 'newVersion' attribute of <assemblyIdentity name="PostSharp.Public" publicKeyToken="b13fd38b8f9c99d7" /> as mentioned above but also have to modify that of <assemblyIdentity name="PostSharp.Core" publicKeyToken="b13fd38b8f9c99d7" /> to the newVersion. Just note there might be minor difference between the version of PostSharp.Public.dll and PostSharp.Core.dll. For example, in PostSharp Beta 2 release, the version of PostSharp.Public.dll is 1.0.5.192 while that of PostSharp.Core.dll is 1.0.5.193.

2. Product Scenario

   In product scenario, you don't have to install our BtM .NET Toolkit but just need to shipp necessary BtM dlls together with your application output (Refer to3.1 for more). To make sure your application instrumented by BtM .NET Toolkit works smoothly with newer version of Postsharp. All you have to do is to ship the above mentioned two xml files: BTMAttribute.dll.config and BTMWeaver.dll.config, together with your application output and necessary BtM dlls.

   The content of BTMAttribute.dll.config:

   <?xml version="1.0"?>
   <configuration>
   <runtime>
   <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
   <dependentAssembly>
   <assemblyIdentity name="PostSharp.Public" publicKeyToken="b13fd38b8f9c99d7" />
   <publisherPolicy apply="yes" />
   <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="1.0.5.192" />
   </dependentAssembly>
   </assemblyBinding>
   </runtime>
   </configuration>

   The content of BTMAttribute.dll.config:

   <?xml version="1.0"?>
   <configuration>
   <runtime>
   <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
   <dependentAssembly>
   <assemblyIdentity name="PostSharp.Public" publicKeyToken="b13fd38b8f9c99d7" />
   <publisherPolicy apply="yes" />
   <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="1.0.5.192" />
   </dependentAssembly>
   <dependentAssembly>
   <assemblyIdentity name="PostSharp.Core" publicKeyToken="b13fd38b8f9c99d7" />
   <publisherPolicy apply="yes" />
   <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="1.0.5.193" />
   </dependentAssembly>
   </assemblyBinding>
   </runtime>
   </configuration>

   Note: You should change the 'newVersion' attribute of BTMAttribute.dll.config and BTMWeaver.dll.config to the actual one used in your computer according to the methods described in the above development Scenario section.

1. Open: Start -> All Programs -> Control Panel -> Administrative Tools -> Microsoft .Net Framework 2.0 Configuration


Figure 26 - Microsoft .Net Framework 2.0 Configuration



2. Add the .NET application that you want to manage, in our case, we will choose BTMAttribute.dll and BTMInstrumentManager.dll, which can be found in the BtM toolkit for .NET installation folder.


Figure 27 - Add configured application



3. We will take the process of adding BTMAttribute.dll as an example here. Right click the 'Applications' menu and choose 'Add...', then choose BTMAttribute.dll from BtM Toolkit for .NET installation folder.


Figure 28 - Add BTMAttribute.dll to be configured



4. In order to control the dynamic binding process of BTMAttribute.dll and its postsharp reference, we have to add configured assemblies next.


Figure 29 - Configure BTMAttribute.dll



5. Since BTMAttribute.dll only have one postsharp reference : Postsharp.Public.dll , so we only have to add Postsharp.Public.dll here.


Figure 30 - Configure BTMAttribute.dll reference PostSharp.Public.dll



6. After we have chosen the PostSharp.Public.dll, the PostSharp.Public Properites dialouge will pop out.


Figure 31 - PostSharp.Public.dll Properities



7. Click the 'Binding Policy' tag, and you can set the dynamic reference binding property here. There are two methods to redirect the reference, one is to redirect the very Postsharp version our BtM Toolkit for .NET using to the newly released Postsharp version, for example in the picture below, we suppose our BtM Toolkit for .NET reference postsharp.public whose version is 1.0.4.162, and the newly released postsharp version is 1.0.5.192. But in the actual scenario, our BtM Toolkit for .NET BTMAttribute.dll reference postsharp.public.dll 1.0.5.192, so u can set the requested version to be 1.0.5.192.


Figure 32 - Version Redirect of PostSharp.Public.dll _ 1



8. Or, you can also set the requested version region to include all possible requested versions.


Figure 33 - Version Redirect of PostSharp.Public.dll _ 2



9. Now, you have already configured the BTMAttribute.dll and you can just configure BTMWeaver.dll in the same way. Just note, our BTMWeaver.dll reference two postsharp assemblies: PostSharp.Public.dll (1.0.5.192) and PostSharp.Core.dll (1.0.5.193). Congratulations! The configuration has been done! And now, your mmc will look similar to:


Figure 34 - Configuration Done

Copyright © 2007 IBM Corporation and others. All rights reserved. This document and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
Author: Yue Yu and Yun Song Huang