Command-line Execution

Team System abstracts the process of calling several utilities to conduct profiling. You can use these utilities directly if you need more control or to integrate your profiling with an automated batch process, such as your nightly build. The general flow is:

• Configure the target (if necessary) and environment

• Start the data logging engine

• Run the target application

• When the application has completed, stop the logging data engine

• Generate the session report

These utilities can be found in your Visual Studio installation directory under \Team Tools\Performance Tools. For help with any of the utilities, supply a /? argument after the utility name.

Configuring instrumentation

If you wish to instrument a binary for profiling, use the VSInstr.exe utility as follows:

      VSInstr Utilities.dll

This will fully instrument all of the methods in the Utilities assembly. If you do not want all of the methods to be instrumented, use the /exclude flag and specify the method you wish to exclude. For example, the following will instrument all Utilities.dll methods except Utilities.Math.LaplaceTransform:

      VSInstr Utilities.dll /exclude:Utilities.Math::LaplaceTransform

Similarly, you can use the /include flag to include only the methods you specify. All others will remain uninstrumented.

The /include and /exclude options can be supplied multiple times, but you cannot use both /include and /exclude options at the same time.

Note

As mentioned earlier in this chapter, instrumenting a signed assembly will invalidate that assembly because the assembly will no longer match the signature. To remedy this, add a call to the command-line tool sn.exe, supplying the assembly to sign and the keyfile to use.

Setting environment variables

Profiling requires that several Windows environment variables be set. This is important because it allows the profiling subsystem to be invoked in a target process. This is done automatically for you by the Team System IDE, but when using the command line, you need to use the VSPerfClrEnv.cmd utility, which establishes these settings for you.

Instrumentation

If you are running an instrumented session (sometimes referred to as tracing,) use the /traceon argument:

      VSPerfClrEnv /traceon

If you also wish to collect allocation data (akin to setting the Allocations Only option in your session's General properties), use the /tracegc argument instead:

      VSPerfClrEnv /tracegc

Remember that specifying this option will cause profiling to have a greater impact on the profiled application's performance.

Sampling

For sampling, you can choose to launch the application from the profiler, in which case you will not need to run VSPerfClrEnv. If you will not launch the application from the profiler, use the /sampleon argument:

      VSPerfClrEnv /sampleon

You can collect managed type allocation details by providing the /samplegc argument instead of /sampleon. If you are not using VSPerfClrEnv, you could supply the /gc argument to the VSPerfCmd utility, described in the section "Executing a profiling session," later in this chapter.

Profiling a Windows service or ASP.NET application

If you need to profile an ASP.NET application or a Windows Service that is automatically run on system startup, use the /globaltraceon options to VSPerfClrEnv. This will set the required variables in the Windows registry so they will automatically be available when Windows starts, which will enable any managed process, including Windows services that automatically start, to hook into the profiling system.

Clearing environment settings

Once profiling is complete, use the /off argument (or /globaloff) to clear the environment variables:

      VSPerfClrEnv /off

Executing a profiling session

Once the environment has been configured, you need to start the profiling monitor by using the VSPerfCmd.exe utility, minimally supplying the /start and /output arguments. You specify sampling or instrumentation (trace) and a filename in which the profiling data will be stored.

This command will start the logging engine, watching for an instrumented binary:

       VSPerfCmd /start:trace /output:SampleSession.vsp

The following command starts monitoring for a sampled application:

      VSPerfCmd /start:sample /output:SampleSession.vsp

Once the logging monitor has started, run your application. If you are running an instrumented profile, ensure that you are using the instrumented versions of your binaries.

For sampling profiles, you can collect details on managed type allocations by supplying the /gc argument. However, in order to use the /gc argument, you must also use the /launch option, supplying the command to launch the sampled application. Instrumentation-based profiles must use the /tracegc argument to VSPerfClrEnv as described above. The following command starts monitoring for a sampled application, collecting allocation data for managed types:

      VSPerfCmd /start:sample /output:DemoConsoleSession.vsp /launch:DemoConsole.exe /gc

When the application has completed, shut down the monitoring engine. Do this with the /shutdown argument to VSPerfCmd:

      VSPerfCmd /shutdown

This will stop the monitor and store all collected data in the file specified with the /output argument.

Note

VSPerfCmd has many advanced options for maximum flexibility. Use the /? argument to get a full list of available arguments with brief descriptions.

Generating reports

Once the monitor has completed and created the profile data file (such as SampleSession.vsp), you can generate a report by using the VSPerfReport.exe utility, supplying the name of the profile data file.

Note

You may also import the file directly into the Team System IDE by using the Performance Explorer. Right-click the Reports node and choose Add Report, specifying the data file you wish to import.

The /summary:<types< argument specifies which report(s) to generate (Module, Function, CallTree, etc.). This can be a comma-delimited list of types or you can use all to generate all report types:

      VSPerfReport SampleSession.vsp /summary:all

You can supply the optional /xml argument to output the report in XML format.

Use the optional /output argument to specify a file for the report.

For example, the following command will generate an XML call tree report to a file named CallTreeReport.xml:

      VSPerfReport SampleSession.vsp /summary:CallTree /xml /output:CallTreeReport.xml