This post pertains to the IntelliTrace Standalone Collector, a new feature associated with Visual Studio 2012.  The Standalone Collector allows you to collect IntelliTrace logging information on one machine (e.g. a production server) and analyze the log on another machine (e.g. the dev machine in your office).  This post will specifically provide some example scripts that may be helpful if you want to collect IntelliTrace information on your server via a remote PowerShell session.

General information about IntelliTrace collection with the Standalone Collector can be found here (MSDN), or you can watch this video from Tech Ed 2012.  The IntelliTrace Standalone Collector is free for anyone to download (find the Microsoft Visual Studio 2012 Release Candidate here), but opening the logs requires Visual Studio Ultimate.

Disclaimer: I am not an expert with PowerShell, so some of this code may violate best practices or otherwise reveal my naïveté.  My goal is simply to provide some initial examples that you can modify to suit your needs.

High-Level Steps

• Set Up an IntelliTrace Collection Folder
• Set Up a Remote PowerShell Session
• Start IntelliTrace Collection on an Application Pool
• Reproduce an Issue
• Stop IntelliTrace Collection on an Application Pool
• Review IntelliTrace Logs

Set Up an IntelliTrace Collection Folder

1. Create a folder on your server machine (assumed below to be C:IntelliTraceCollection) 
2. Grant write access for the folder to BUILTINIIS_IUSRS

Steps 1-2 can be run using a PowerShell script like the following, and if you have the right permissions, there is no reason you couldn’t also run this remotely, as described below:

# SetupCollectionFolder.ps1

$Drive=”C:”
$FolderName=”IntelliTraceCollection”

New-Item -Path $Drive -Name $FolderName -Type Directory

$StartingDir=”$Drive$FolderName”
Set-Location $StartingDir

$Right=”Write”
$Principal=”BUILTINIIS_IUSRS”
$Rule=New-Object System.Security.AccessControl.FileSystemAccessRule($Principal,$Right,”Allow”)

$Acl=Get-Acl .
$Acl.SetAccessRule($Rule)

Set-Acl . $Acl

      3. Expand IntellitraceCollection.cab to your collection folder through a command like the following.  Note that this file will be located under the x86 Program Files directory at Microsoft Visual Studio 11.0Common7IDECommonExtensionsMicrosoftIntelliTrace11.0.0, or can be downloaded from MSDN (Microsoft Visual Studio 2012 Release Candidate here):

Expand IntelliTraceCollection.cab -f:* C:IntelliTraceCollection 

Note: I get an error if I try to run this through a remote PowerShell session.  You may wish to run this while logged in to the server.  It is also possible to expand the .cab file to a share on your server machine from your client machine, or to a mutually-accessible share from which you can copy files to your server via a remote session.  These may not be best practices for your environment, but if you want to script them, here are some samples.  I’m assuming here that you are running on a dev machine with Visual Studio Ultimate installed to the default location:

# ExpandIntelliTraceCollectorFiles.ps1

# This would be run from your client machine

$SharePath=”\MACHINENAMESHAREPATH”
$UserName=”DOMAINUSERNAME”
$Password=”PASSWORD1”

net use $SharePath $Password /User:$Username

$VSPath=”C:Program FilesMicrosoft Visual Studio 11.0Common7IDE”
$IntelliTrace11Path=”CommonExtensionsMicrosoftIntelliTrace11.0.0″
$CabFilePath=”$VSPath$IntelliTrace11PathIntelliTraceCollection.cab”

Expand $CabFilePath -f:* $SharePath

# CopyIntelliTraceCollectorFiles.ps1

# This would be run on the server, or via a remote PowerShell session

$Drive=”C:”
$FolderName=”IntelliTraceCollection”
$StartingDir=”$Drive$FolderName”

$SharePath=”\MACHINENAMESHAREPATH”
$UserName=”DOMAINUSERNAME”
$Password=”PASSWORD1”

net use $SharePath $Password /User:$Username

Copy-Item $SharePath* -Destination $StartingDir -Recurse

Note also that expanding in the Windows shell does not preserve the proper directory structure of these files.

Set Up a Remote PowerShell Session

The primary advantage of a remote PowerShell session is that it carries much less overhead, since it saves your server the trouble of spinning up UI.  To enable remote PowerShell on the server machine, you (or someone) must run WinRM QuickConfig from an elevated command prompt and say yes when prompted to enable a firewall exception:

C:Windowssystem32>WinRM QuickConfig
WinRM already is set up to receive requests on this machine.
WinRM is not set up to allow remote access to this machine for management.
The following changes must be made:

Create a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine
Enable the WinRM firewall exception.

Make these changes [y/n]?

After this has been done, you will be able to enter remote PowerShell sessions on the server with a command like this:

Enter-PSSession -ComputerName COMPUTERNAME

Note that you can exit the session with Exit-PSSession.

Start IntelliTrace Collection on an Application Pool

The following example PowerShell script could be run to start collection:

# StartIntelliTraceCollection.ps1

$Drive=”C:”
$FolderName=”IntelliTraceCollection”

Set-Location $Drive$FolderName

Import-Module .Microsoft.VisualStudio.Intellitrace.PowerShell.dll

$AppPool=”DEFAULTAPPPOOL”
$OutputPath=”.”

# For high collection, use .collection_plan.ASP.NET.trace.xml

$CollectionPlan=”.collection_plan.ASP.NET.default.xml”

Start-IntelliTraceCollection $AppPool $CollectionPlan $OutputPath

Reproduce an Issue

Once you have started IntelliTrace collection on a given application pool, it will be recycled, and you can use the application to hit the scenario in which you are interested.  If you know how to reproduce an issue, you may simply want to browse to the application from your client machine and do so.  Under other circumstances, you might wait for a customer to hit the issue on your production server, or something like that.  The key point is that the code in which you are interested must execute while IntelliTrace is collecting against the application pool.

During collection, you can use Get-IntelliTraceCollectionStatus to see information regarding the status of each of your IIS app pools.  For example:

PS C:IntelliTraceCollection> Get-IntelliTraceCollectionStatus

ApplicationPool    : DefaultAppPool
ProcessId          : 2336
ProcessStartTime   : 7/5/2012 11:23:50 AM
CollectionPlanPath : C:WindowsTempDefaultAppPool_collection_plan.ASP.NET.default.xml
OutputPath         : C:IntelliTraceCollectionw3wp_00000920_120705_112350.iTrace

…

Stop IntelliTrace Collection on an Application Pool

During collection, trace information gets stored to IntelliTrace log files in the specified output path ($OutputPath above) on a per-process basis.  Once you think an issue has been reproduced during IntelliTrace Collection, you can use Stop-IntelliTraceCollection to stop collection against a particular application pool, or Checkpoint-IntelliTraceCollection to generate a snapshot log of what has been traced so far.  The following script demonstrates how you might stop collection:

# StopIntelliTraceCollection.ps1

Import-Module .Microsoft.VisualStudio.Intellitrace.PowerShell.dll

$AppPool=”DEFAULTAPPPOOL”

Stop-IntelliTraceCollection “$AppPool”

Review IntelliTrace Logs

Once you have stopped collection, you can view some basic information about a particular IntelliTrace log file(,iTrace) using Get-IntelliTraceFileInfo.  For example:

PS C:IntelliTraceCollection> Get-IntelliTraceFileInfo .w3wp_00000920_120705_112350.iTrace

Path             : C:IntelliTraceCollectionw3wp_00000920_120705_112350.iTrace
ProcessName      : C:windowssystem32inetsrvw3wp.exe
ProcessId        : 2336
ProcessStartTime : 7/5/2012 11:23:50 AM
ProcessStopTime  : 7/5/2012 11:40:55 AM
ApplicationPool  : DefaultAppPool
CheckpointTime   :
TraceDuration    : 00:16:59.4850000

To view the logged information in detail and step through code, you will need to copy the log file(s) from your output directory (C:IntelliTraceCollection if you follow the above instructions exactly) to your dev machine.  The following is one final PowerShell script that you can adapt to carry out this step:

# CopyIntelliTraceLogs.ps1

$Drive=”C:”
$FolderName=”IntelliTraceCollection”

Set-Location $Drive$FolderName

$SharePath=”\MACHINENAMESHAREPATH”
$UserName=”DOMAINUSERNAME”
$Password=”PASSWORD1”

net use $SharePath $Password /User:$Username

Copy-Item .*.itrace $CopyToLoc

Remove-Item -Path .*.itrace

Opening an Intellitrace log requires Visual Studio Ultimate, and if you are not already familiar with this scenario, the following resources may be helpful in explaining the process:

• How to: Save, Open, Read, and Debug IntelliTrace Recordings
• Navigating with IntelliTrace
• IntelliTrace Web Requests

The following resources can also provide some more robust general information about IntelliTrace:

• Collecting IntelliTrace Information
• Collecting IntelliTrace Data Everywhere
• Advanced IntelliTrace in Production with Visual Studio 2012 (video)