IntelliTrace スタンドアロンコレクターの使用 (C#、Visual Basic)

IntelliTrace スタンドアロンコレクターを使用すると、ターゲットコンピューターに Visual Studio をインストールしたり、ターゲットシステムの環境を変更したりすることなく、運用サーバーやその他の環境でアプリの IntelliTrace 診断データを収集できます。 IntelliTrace スタンドアロンコレクターは、Web、SharePoint、WPF、および Windows フォームアプリで動作します。データの収集が完了したら、コレクターを削除してアンインストールします。

注

運用サーバーの問題を診断するための推奨される方法については、デプロイ後の問題の診断に関する記事を参照してください。

必要条件

.NET Framework 3.5 以降
.iTrace ファイルを開くための開発用コンピューターまたは他のコンピューター上の Visual Studio Enterprise (Professional または Community エディションではありません)

注

シンボル (.pdb) ファイルを保存してください。 IntelliTrace を使用してデバッグし、コードをステップ実行するには、一致するソースファイルとシンボルファイルが必要です。デプロイ後の問題の診断を参照してください。

よくある質問
コレクターで動作するアプリは何ですか?
使い始めるにはどうすればよいですか?
アプリの速度を低下させることなく、データを最大限に活用するにはどうすればよいですか?
IntelliTrace データは他にどこで取得できますか?

コレクターで動作するアプリは何ですか?

インターネットインフォメーションサービス (IIS) バージョン 7.0、7.5、8.0、12.0、および 16.0 でホストされている ASP.NET Web アプリ
SharePoint 2010 および SharePoint 2013 アプリケーション
Windows Presentation Foundation (WPF) アプリと Windows フォームアプリ。

どのように使い始めたらよいですか?

コレクターをインストールする
コレクターディレクトリのアクセス許可を設定する
IntelliTrace PowerShell コマンドレットをインストールして Web アプリまたは SharePoint アプリケーションのデータを収集する
.iTrace ファイルディレクトリのアクセス許可を設定する
Web アプリまたは SharePoint アプリケーションからデータを収集する

-又は-

マネージドアプリからデータを収集する
Visual Studio Enterprise で .iTrace ファイルを開く

コレクターをインストールする

アプリのサーバーでコレクターディレクトリを作成します (例: C:\IntelliTraceCollector)
Visual Studio のインストールフォルダーからコレクターを取得します。
1. コレクターがインストールされているフォルダーから IntelliTraceCollection.cab をコピーします。次に例を示します。
  
  ..\Microsoft Visual Studio\18\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  ..\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  または、以前のバージョンの Visual Studio の場合:
  
  ..\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
2. コレクターディレクトリに IntelliTraceCollection.cab を配置します (例: C:\IntelliTraceCollector)
IntelliTraceCollection.cabを展開します。
1. アプリのサーバーで、管理者としてコマンドプロンプトウィンドウを開きます。
2. コレクターディレクトリを参照します (例: C:\IntelliTraceCollector)
3. 末尾のピリオド (.) を含む expand コマンドを使用して、IntelliTraceCollection.cab展開します。
  
  expand /f:* IntelliTraceCollection.cab .
  
  注
  
  ピリオド (.) は、ローカライズされたコレクションプランを含むサブフォルダーを保持します。

コレクターディレクトリのアクセス許可を設定する

アプリのサーバーで、管理者としてコマンドプロンプトウィンドウを開きます。
Windows icacls コマンドを使用して、サーバー管理者にコレクターディレクトリへの完全なアクセス許可を付与します。例えば次が挙げられます。

icacls "C:\IntelliTraceCollector" /grant " <Domain\AdministratorID>":F
Web アプリまたは SharePoint アプリケーションのデータを収集するには:
1. IntelliTrace PowerShell コマンドレットを実行するユーザーに、コレクターディレクトリに対する完全なアクセス許可を付与します。
  
  例えば次が挙げられます。
  
  icacls "C:\IntelliTraceCollector" /grant " <Domain\UserID>":F
2. Web アプリまたは SharePoint アプリケーションのアプリケーションプールに、コレクターディレクトリに対する読み取りと実行のアクセス許可を付与します。
  
  例えば次が挙げられます。
  - DefaultAppPool アプリケーションプール内の Web アプリの場合:
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX
  - SharePoint - 80 アプリケーションプール内の SharePoint アプリケーションの場合:
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

IntelliTrace PowerShell コマンドレットをインストールして Web アプリまたは SharePoint アプリケーションのデータを収集する

アプリのサーバーで、PowerShell が有効になっていることを確認します。ほとんどのバージョンの Windows Server では、 サーバーマネージャー 管理ツールでこの機能を追加できます。
IntelliTrace PowerShell コマンドレットをインストールします。
1. 管理者として PowerShell コマンドウィンドウを開きます。
  1. [スタート]、[すべてのプログラム]、[アクセサリ]、[Windows PowerShell] の順に選択します。
  2. 次のいずれかの手順を選択します。
    - 64 ビットオペレーティングシステムで、 Windows PowerShell のショートカットメニューを開きます。 [ 管理者として実行] を選択します。
    - 32 ビットオペレーティングシステムで、 Windows PowerShell (x86) のショートカットメニューを開きます。 [ 管理者として実行] を選択します。
2. PowerShell コマンドウィンドウで、 Import-Module コマンドを使用して Microsoft.VisualStudio.IntelliTrace.PowerShell.dllをインポートします。
  
  例えば次が挙げられます。
  
  Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

.iTrace ファイルディレクトリのアクセス許可を設定する

アプリのサーバーで、.iTrace ファイルディレクトリを作成します (例: C:\IntelliTraceLogFiles)。
注
- アプリの速度低下を回避するには、あまりアクティブではないローカルの高速ディスク上の場所を選択します。
  - .iTrace ファイルとコレクターファイルを同じ場所に配置できます。ただし、Web アプリまたは SharePoint アプリケーションがある場合は、この場所がアプリケーションをホストするディレクトリの外部にあることを確認してください。
Important
- .iTrace ファイルディレクトリは、コレクターで動作する必要がある ID のみに制限します。 .iTrace ファイルには、ユーザー、データベース、その他のソースの場所からのデータ、接続文字列などの機密情報が含まれている場合があります。IntelliTrace は、メソッドパラメーターまたは戻り値として渡すデータを記録できるためです。
  - .iTrace ファイルを開くことができるユーザーが機密データを表示する権限を持っていることを確認します。 .iTrace ファイルを共有するときは注意が必要です。他のユーザーがアクセスできる必要がある場合は、ファイルを安全な共有場所にコピーします。
Web アプリまたは SharePoint アプリケーションの場合は、そのアプリケーションプールに .iTrace ファイルディレクトリへの完全なアクセス許可を付与します。 Windows icacls コマンドを使用することも、Windows エクスプローラー (またはエクスプローラー) を使用することもできます。

例えば次が挙げられます。
- Windows icacls コマンドを使用してアクセス許可を設定するには:
  - DefaultAppPool アプリケーションプール内の Web アプリの場合:
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F
  - SharePoint - 80 アプリケーションプール内の SharePoint アプリケーションの場合:
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F
    
    -又は-
- Windows エクスプローラー (またはファイルエクスプローラー) でアクセス許可を設定するには:
  1. .iTrace ファイルディレクトリの プロパティ を開きます。
  2. [セキュリティ] タブで、[編集], [追加] を選択します。
  3. [このオブジェクトの種類を選択] ボックスに組み込みのセキュリティプリンシパルが表示されていることを確認します。存在しない場合は、[ オブジェクトの種類] を選択して追加します。
  4. ローカルコンピューターが [ この場所から ] ボックスに表示されていることを確認します。表示されない場合は、[ 場所 ] を選択して変更します。
  5. [ 選択するオブジェクト名を入力 してください] ボックスに、Web アプリまたは SharePoint アプリケーションのアプリケーションプールを追加します。
  6. 名前を解決するには、[名前の確認] を選択します。 [OK]を選択して下さい。
  7. アプリケーションプールに フルコントロールがあることを確認します。

Web アプリまたは SharePoint アプリケーションからデータを収集する

データの収集を開始するには、管理者として PowerShell コマンドウィンドウを開き、次のコマンドを実行します。

Start-IntelliTraceCollection " <ApplicationPool>"<PathToCollectionPlan><FullPathToITraceFileDirectory>

Important

このコマンドを実行した後、 Y と入力して、データの収集を開始することを確認します。

たとえば、 SharePoint - 80 アプリケーションプール内の SharePoint アプリケーションからデータを収集するには、次のようにします。

Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"

名前	Description
ApplicationPool	アプリケーションが実行されるアプリケーションプールの名前
PathToCollectionPlan	コレクションプランへのパス。コレクターの設定を構成する .xml ファイル。コレクターに付属するプランを指定できます。次のプランは、Web アプリと SharePoint アプリケーションで機能します。 - collection_plan.ASP.NET.default.xml 例外、データベース呼び出し、Web サーバー要求など、IntelliTrace イベントと SharePoint イベントのみを収集します。 - collection_plan.ASP.NET.trace.xml 関数呼び出しと、collection_plan.ASP.NET.default.xml内のすべてのデータを収集します。このプランは詳細な分析に適していますが、collection_plan.ASP.NET.default.xml以上にアプリの速度が低下する可能性があります。アプリの速度低下を回避するには、これらのプランをカスタマイズするか、独自のプランを作成します。セキュリティを確保するには、コレクターファイルと同じ安全な場所にカスタムプランを配置します。「 IntelliTrace コレクションプランの作成とカスタマイズ」を参照してください。また、アプリの速度を低下させずに最も多くのデータを取得する方法を教えてください。手記：既定では、.iTrace ファイルの最大サイズは 100 MB です。 .iTrace ファイルがこの制限に達すると、コレクターはファイルの最も古いエントリを削除して、新しいエントリ用の領域を作成します。この制限を変更するには、コレクションプランの `MaximumLogFileSize` 属性を編集します。これらのコレクションプランのローカライズされたバージョンはどこにありますか? ローカライズされたプランは、コレクターのサブフォルダーにあります。
FullPathToITraceFileDirectory	.iTrace ファイルディレクトリへの完全なパス。セキュリティに関する注意: 相対パスではなく、完全なパスを指定します。

コレクターはアプリケーションプールにアタッチし、データの収集を開始します。

この時点で .iTrace ファイルを開くことができますか? いいえ。ファイルはデータ収集中にロックされます。

問題を再現します。
.iTrace ファイルのチェックポイントを作成するには、次の構文を使用します。

Checkpoint-IntelliTraceCollection " <ApplicationPool>"
コレクションの状態を確認するには、次の構文を使用します。

Get-IntelliTraceCollectionStatus
データの収集を停止するには、次の構文を使用します。

Stop-IntelliTraceCollection " <ApplicationPool>"

Important

このコマンドを実行した後、 Y と入力して、データの収集を停止することを確認します。そうしないと、コレクターがデータの収集を続けるか、iTrace ファイルがロックされたままになるか、ファイルに有用なデータが含まれていない可能性があります。
Visual Studio Enterprise で .iTrace ファイルを開く

マネージドアプリからデータを収集する

アプリを起動して同時にデータを収集するには、次の構文を使用します。

<IntelliTraceコレクター実行可能ファイルへの完全パス>\IntelliTraceSC.exe launch /cp:<コレクションプランへのパス>/f:<ITraceファイルディレクトリとファイル名への完全パス><アプリ実行可能ファイルとファイル名へのパス>

たとえば、 MyApp という名前のアプリからデータを収集するには、次のようにします。

C:IntelliTraceCollectorIntelliTraceSC.exe launch /cp:"C:IntelliTraceCollectorcollection_plan.ASP.NET.default.xml" /f:"C:IntelliTraceLogFilesMyApp.itrace" "C:MyAppMyApp.exe"

名前	Description
FullPathToIntelliTraceCollectorExecutable	コレクター実行可能ファイルへの完全パス (IntelliTraceSC.exe
PathToCollectionPlan	コレクションプランへのパス。コレクターの設定を構成する .xml ファイル。コレクターに付属するプランを指定できます。次のプランは、マネージドアプリに対して機能します。 - collection_plan.ASP.NET.default.xml 例外、データベース呼び出し、Web サーバー要求など、IntelliTrace イベントのみを収集します。 - collection_plan.ASP.NET.trace.xml 関数呼び出しと、collection_plan.ASP.NET.default.xml内のすべてのデータを収集します。このプランは詳細な分析に適していますが、collection_plan.ASP.NET.default.xml以上にアプリの速度が低下する可能性があります。アプリの速度低下を回避するには、これらのプランをカスタマイズするか、独自のプランを作成します。セキュリティを確保するには、コレクターファイルと同じ安全な場所にカスタムプランを配置します。「 IntelliTrace コレクションプランの作成とカスタマイズ」を参照してください。また、アプリの速度を低下させずに最も多くのデータを取得する方法を教えてください。手記：既定では、.iTrace ファイルの最大サイズは 100 MB です。 .iTrace ファイルがこの制限に達すると、コレクターはファイルの最も古いエントリを削除して、新しいエントリ用の領域を作成します。この制限を変更するには、コレクションプランの `MaximumLogFileSize` 属性を編集します。これらのコレクションプランのローカライズされたバージョンはどこにありますか? ローカライズされたプランは、コレクターのサブフォルダーにあります。
FullPathToITraceFileDirectoryAndFileName	.iTrace ファイルディレクトリへの完全なパスと、拡張子が .itrace の .iTrace ファイル名。セキュリティに関する注意: 相対パスではなく、完全なパスを指定します。
PathToAppExecutableFileAndFileName	マネージドアプリのパスとファイル名

アプリを終了してデータ収集を停止します。
Visual Studio Enterprise で .iTrace ファイルを開く

Visual Studio Enterprise で .iTrace ファイルを開く

注

IntelliTrace を使用してデバッグし、コードをステップ実行するには、一致するソースファイルとシンボルファイルが必要です。デプロイ後の問題の診断を参照してください。

.iTrace ファイルを移動するか、Visual Studio Enterprise を使用するコンピューターにコピーします (Professional エディションまたは Community エディションではありません)。
Visual Studio の外部にある .iTrace ファイルをダブルクリックするか、Visual Studio 内からファイルを開きます。

Visual Studio に IntelliTrace の概要ページが 表示されます。ほとんどのセクションでは、イベントまたはその他の項目を確認し、項目を選択し、イベントが発生した時点とタイミングで IntelliTrace を使用してデバッグを開始できます。保存された IntelliTrace データの使用を参照してください。

注

IntelliTrace を使用してデバッグし、コードをステップ実行するには、開発用コンピューターに一致するソースファイルとシンボルファイルが必要です。デプロイ後の問題の診断を参照してください。

アプリの速度を低下させることなく、データを最大限に活用するにはどうすればよいですか?

IntelliTrace は大量のデータを収集できるため、アプリのパフォーマンスへの影響は、IntelliTrace が収集するデータと分析するコードの種類によって異なります。実稼働サーバーでの IntelliTrace コレクションの最適化を参照してください。

アプリの速度を低下させずにデータを最大限に活用する方法を次に示します。

コレクターは、問題があると思う場合、または問題を再現できる場合にのみ実行します。

収集を開始し、問題を再現してから、収集を停止します。 Visual Studio Enterprise で .iTrace ファイルを開き、データを調べます。 Visual Studio Enterprise で .iTrace ファイルを開くを参照してください。
Web アプリと SharePoint アプリケーションの場合、コレクターは、指定されたアプリケーションプールを共有するすべてのアプリのデータを記録します。コレクションプラン内の 1 つのアプリに対してのみモジュールを指定できる場合でも、同じアプリケーションプールを共有するアプリの速度が低下する可能性があります。

コレクターが他のアプリの速度を低下させるのを防ぐには、各アプリを独自のアプリケーションプールでホストします。
IntelliTrace がデータを収集するコレクション計画のイベントを確認します。コレクション計画を編集して、関連性のないイベントや関心のないイベントを無効にします。

イベントを無効にするには、enabled要素の<DiagnosticEventSpecification>属性をfalseに設定します。

<DiagnosticEventSpecification enabled="false">

enabled属性が存在しない場合、イベントは有効になります。

これによりパフォーマンスはどのように向上しますか?
- アプリに関連しないイベントを無効にすると、起動時間を短縮できます。たとえば、Windows ワークフローを使用しないアプリの Windows ワークフローイベントを無効にします。
- レジストリにアクセスしてもレジストリ設定に問題が表示されないアプリのレジストリイベントを無効にすることで、起動時と実行時の両方のパフォーマンスを向上させることができます。
IntelliTrace がデータを収集するコレクション計画のモジュールを確認します。コレクション計画を編集して、関心のあるモジュールのみを含めます。
1. コレクションプランを開きます。 <ModuleList> 要素を検索します。
2. <ModuleList>で、isExclusionList属性を false に設定します。
3. <Name>要素を使用して、各モジュールを次のいずれかで指定します: ファイル名、名前にその文字列を含む任意のモジュールを指定する文字列値、または公開キー。
  
  たとえば、Fabrikam Fiber Web アプリのメイン Web モジュールからデータを収集するには、次のようなリストを作成します。
```
<ModuleList isExclusionList="false">
   <Name>FabrikamFiber.Web.dll</Name>
</ModuleList>
```
名前に "Fabrikam" が含まれる任意のモジュールからデータを収集するには、次のようなリストを作成します。
```
<ModuleList isExclusionList="false">
   <Name>Fabrikam</Name>
</ModuleList>
```
公開キートークンを指定してモジュールからデータを収集するには、次のようなリストを作成します。
```
<ModuleList isExclusionList="false">
   <Name>PublicKeyToken:B77A5C561934E089</Name>
   <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
   <Name>PublicKeyToken:31BF3856AD364E35</Name>
   <Name>PublicKeyToken:89845DCD8080CC91</Name>
   <Name>PublicKeyToken:71E9BCE111E9429C</Name>
</ModuleList>
```
これによりパフォーマンスはどのように向上しますか?

これにより、アプリの起動時と実行時に IntelliTrace によって収集されるメソッド呼び出し情報やその他のインストルメンテーションデータの量が減ります。このデータを使用すると、次のことができます。
- データを収集した後、コードを1ステップずつ実行します。
- 関数呼び出しに渡され、関数呼び出しから返される値を調べます。
  
  代わりにモジュールを除外しないのはなぜですか?
  
  既定では、コレクションプランでは、 isExclusionList 属性を true に設定してモジュールを除外します。ただし、モジュールを除外しても、リストの条件を満たしていないモジュールからデータが収集される可能性があり、サードパーティのモジュールやオープンソースモジュールなど、関心がない可能性があります。
IntelliTrace で収集されないデータはありますか?

はい。パフォーマンスへの影響を軽減するために、IntelliTrace は、メソッドに渡され、メソッドから返されるプリミティブデータ型の値と、メソッドに渡され、メソッドから返されるトップレベルオブジェクトのフィールド内のプリミティブデータ型の値にデータ収集を制限します。

たとえば、整数のAlterEmployeeを受け取るidメソッドシグネチャと、Employee オブジェクトoldemployeeがあるとします。

public Employee AlterEmployee(int id, Employee oldemployee)

Employee型には、Id、Name、およびHomeAddressという属性があります。 EmployeeとAddress型の間に関連付けリレーションシップが存在します。

コレクターは、id メソッドから返されたEmployee.Id、Employee.Name、Employee、およびAlterEmployee オブジェクトの値を記録します。ただし、コレクターは、 Address オブジェクトが null であったかどうか以外の情報を記録しません。また、他のメソッドがそれらのローカル変数をパラメーターとして使用し、その時点でメソッドパラメーターとして記録しない限り、コレクターは AlterEmployee メソッドのローカル変数に関するデータを記録しません。