設定程式碼剖析環境

發行項
08/12/2011

注意事項
.NET Framework 4 版的程式碼剖析具有一些實質變更。請參閱 .NET Framework 4 中的程式碼剖析以了解影響程式碼剖析環境之設定的變更。

當 Managed 處理序 (應用程式或服務) 啟動時，它就會載入 Common Language Runtime (CLR)。當 CLR 初始化時，它就會評估下列兩個環境變數來決定處理序是否應該連接至程式碼剖析工具：

COR_ENABLE_PROFILING：只有在這個環境變數存在並設定為 1 時，CLR 才會連接到分析工具。
COR_PROFILER：如果 COR_ENABLE_PROFILING 檢查通過，CLR 會連接到有這個 CLSID 或 ProgID (先前必須已儲存在登錄中) 的分析工具。 COR_PROFILER 環境變數是定義為字串，如下列兩個範例所示。
```
set COR_PROFILER={32E2F4DA-1BEA-47ea-88F9-C5DAF691C94A}
set COR_PROFILER="MyProfiler"
```

若要對 CLR 應用程式進行程式碼剖析，在執行應用程式之前，您必須先設定 COR_ENABLE_PROFILING 和 COR_PROFILER 環境變數。此外，您也必須確定已註冊程式碼剖析工具 DLL。

注意事項
從 .NET Framework 4 開始，程式碼剖析工具不需要進行註冊。如需啟動程式碼剖析工具而不將它們註冊為 COM 元件的詳細資訊，請參閱啟動和附加免登錄的程式碼剖析工具。

注意事項
若要在 .NET Framework 4 和更新版本中使用 .NET Framework 2.0、3.0 和 3.5 版程式碼剖析工具，您就必須設定 COMPLUS_ProfAPI_ProfilerCompatibilitySetting 環境變數。如需這個變數的詳細資訊，請參閱程式碼剖析工具相容性設定。

環境變數範圍

COR_ENABLE_PROFILING 和 COR_PROFILER 環境變數的設定方式會決定它們的影響範圍。您可以用下列其中一個方式設定這些變數：

如果您在 ICorDebug::CreateProcess 呼叫中設定變數，它們只會套用至同時執行中的應用程式 (它們也會套用至繼承此環境之應用程式所啟動的其他應用程式)。
如果您在 [命令提示字元] 視窗中設定變數，它們會套用至從該視窗中啟動的所有應用程式。
如果您在使用者層次上設定變數，它們會套用至您使用 Windows 檔案總管啟動的所有應用程式。在設定變數後開啟的 [命令提示字元] 視窗以及從該視窗啟動的任何應用程式都會有這些環境設定。若要在使用者層次上設定環境變數，請以滑鼠右鍵按一下 [我的電腦]，依序按一下 [內容]、[進階] 索引標籤和 [環境變數]，然後將變數加入至 [使用者變數] 清單中。
如果您在電腦層次上設定變數，它們會套用至該電腦上啟動的所有應用程式。在該電腦上開啟的 [命令提示字元] 視窗以及從該視窗啟動的任何應用程式都會有這些環境設定。這表示該電腦上的每個 Managed 處理序都會以您的分析工具開始。若要在電腦層次上設定環境變數，請以滑鼠右鍵按一下 [我的電腦]，依序按一下 [內容]、[進階] 索引標籤和 [環境變數]，然後將變數加入至 [系統變數] 清單中，再重新啟動電腦。重新啟動後，變數即可用於系統範圍。

如果您要分析 Windows 服務，在設定環境變數並註冊分析工具 DLL 之後，必須重新啟動電腦。如需這些考量的詳細資訊，請參閱分析 Windows 服務一節。

其他考量

分析工具類別會實作 ICorProfilerCallback 和 ICorProfilerCallback2 介面。在 .NET Framework 2.0 版中，分析工具必須實作 ICorProfilerCallback2，否則，將不會載入 ICorProfilerCallback2。
在指定的環境中，一個分析工具每次只能分析一個處理序。雖然您可以在不同的環境中註冊兩個不同的程式碼剖析工具，不過每個工具都必須對不同的處理序進行程式碼剖析。程式碼剖析工具必須實作為同處理序 COM 伺服器 DLL，以便與正在進行程式碼剖析的處理序對應至相同的位址空間。這表示分析工具用同處理序執行。 .NET Framework 不支援任何其他類型的 COM 伺服程式。例如，如果分析工具想要監視遠端電腦上的應用程式，它必須在每部電腦上實作收集代理程式。這些代理程式將會批次處理結果並將結果傳送給中央資料收集電腦。
因為分析工具是用同處理序執行個體化的 COM 物件，每個分析的應用程式都會有自己的分析工具複本。因此，單一分析工具執行個體不需要處理來自多個應用程式的資料。不過，您必須在分析工具的記錄程式碼中加入邏輯，防止記錄檔被其他分析的應用程式覆寫。

初始化分析工具

當這兩個環境變數檢查通過時，CLR 會用類似於 COM CoCreateInstance 函式的方式建立分析工具執行個體。分析工具不會透過 CoCreateInstance 的直接呼叫來載入。因此，避免了需要設定執行緒模型的 CoInitialize 呼叫。 CLR 接著會呼叫分析工具中的 ICorProfilerCallback::Initialize 方法。這個方法的簽章如下：

HRESULT Initialize(IUnknown *pICorProfilerInfoUnk)

分析工具必須查詢 pICorProfilerInfoUnk 以取得 ICorProfilerInfo 或 ICorProfilerInfo2 介面指標並儲存它，以便稍後在分析時要求其他資訊。

設定事件告知

程式碼剖析工具會接著呼叫 ICorProfilerInfo::SetEventMask 方法來指定它感興趣的告知分類。例如，如果程式碼剖析工具只對函式進入與離開告知和記憶體回收告知感興趣，它就會指定下列程式碼。

ICorProfilerInfo* pInfo;
pICorProfilerInfoUnk->QueryInterface(IID_ICorProfilerInfo, (void**)&pInfo);
pInfo->SetEventMask(COR_PRF_MONITOR_ENTERLEAVE | COR_PRF_MONITOR_GC)

用這個方式設定告知遮罩，分析工具可以限制它接收的告知。這個方式有助於使用者建立簡單或特殊用途的分析工具。它也會減少因傳送分析工具將忽略的告知而浪費掉的 CPU 時間。

特定分析工具事件是不可變的。這表示，這些事件一旦在 ICorProfilerCallback::Initialize 回呼中設定，便無法關閉它們，也無法開啟新事件。嘗試變更不可變的事件，將會使 ICorProfilerInfo::SetEventMask 傳回失敗的 HRESULT。

分析 Windows 服務

Windows 服務程式碼剖析就像 Common Language Runtime 應用程式程式碼剖析一樣。這兩種分析作業都是透過環境變數啟用的。因為作業系統啟動時會同時啟動 Windows 服務，所以在系統啟動前，本主題先前所討論的環境變數必須已存在並設定為必要值。此外，分析 DLL 必須已在系統上註冊。

在您設定 COR_ENABLE_PROFILING 和 COR_PROFILER 環境變數並註冊分析工具 DLL 後，應重新啟動目標電腦，讓 Windows 服務可以偵測這些變更。

請注意，這些變更會啟用系統範圍分析。若要防止後續執行的每個 Managed 應用程式進行分析，在重新啟動目標電腦後，您應該刪除系統環境變數。

這個技巧也會導致每個 CLR 處理序進行分析。分析工具應該在其 ICorProfilerCallback::Initialize 回呼中加入邏輯，以偵測目前處理序是否為所需。如果不是，分析工具可以讓回呼失敗，而不執行初始化。

請參閱

概念

分析概觀

共用方式為