共用方式為

程式碼剖析工具相容性設定

  • 發行項

根據預設，在 .NET Framework 4 版中，Common Language Runtime (CLR) 只會載入並使用針對 .NET Framework 4 所建置的程式碼剖析工具。 除非明確指定，否則 CLR 不會載入或執行針對 .NET Framework 2.0、3.0 或 3.5 版建置的程式碼剖析工具 (在本主題中，「2.0 版程式碼剖析工具」這個詞是指針對 .NET Framework 2.0、3.0 和 3.5 版建置的程式碼剖析工具)。

程式碼剖析工具使用者必須使用 COMPLUS_ProfAPI_ProfilerCompatibilitySetting 環境變數來明確選擇使用 2.0 版程式碼剖析工具。 用於 .NET Framework 4 中的 2.0 版程式碼剖析工具具有下列行為：

  • .NET Framework 2.0 版的程式碼剖析 API 會繼續根據 2.0 版文件，在 .NET Framework 4 中運作。

  • .NET Framework 4 無法保證未記載的 2.0 版程式碼剖析 API 或 CLR 行為。 相依於未記載行為的 2.0 版程式碼剖析工具不保證可在 .NET Framework 4 中運作。請注意，這個相容性設定不會提供 CLR 2.0 行為的回溯相容性。

COMPLUS_ProfAPI_ProfilerCompatibilitySetting

設定 COMPLUS_ProfAPI_ProfilerCompatibilitySetting 環境變數之前，您必須先設定 COR_PROFILER 或 COR_ENABLE_PROFILING 環境變數 (如需相關指示，請參閱設定程式碼剖析環境)。

您可以將 COMPLUS_ProfAPI_ProfilerCompatibilitySetting 環境變數設定為三個值的其中之一，如下表所示。

注意事項注意事項

在 .NET Framework 3.5 版和先前的版本中，CLR 不支援 COMPLUS_ProfAPI_ProfilerCompatibilitySetting 變數。如果已經設定了 COR_PROFILER 或 COR_ENABLE_PROFILING 環境變數，它就一定會嘗試載入程式碼剖析工具。

設定

CLR 行為

EnableV2Profiler

載入並啟動 2.0 版程式碼剖析工具。

DisableV2Profiler

停用 2.0 版程式碼剖析工具，但不卸載它們。 .NET Framework 4 程式碼剖析工具不受影響。 這是預設值。

PreventLoad

不載入任何程式碼剖析工具，不論撰寫此程式碼剖析工具的目標 .NET Framework 版本為何。

詳細的行為如下所示：

  • EnableV2Profiler

    .NET Framework 4 CLR 會載入並使用可用的程式碼剖析工具，不論撰寫此程式碼剖析工具的目標 .NET Framework 版本為何。 在同處理序並存程式碼剖析中，如果 .NET Framework 2.0 版 CLR 先在處理序中載入程式碼剖析工具，.NET Framework 4 CLR 就不會重新載入該 2.0 版程式碼剖析工具。

  • DisableV2Profiler (預設值)

    .NET Framework 4 CLR 會呼叫程式碼剖析工具的 IUnknown::QueryInterface 方法來找出 ICorProfilerCallback3 介面，藉以載入程式碼剖析工具並判斷其版本。 

    • 如果程式碼剖析工具會實作 ICorProfilerCallback3，它就是 .NET Framework 4 版程式碼剖析工具，而且 CLR 會繼續使用它。

    • 如果程式碼剖析工具不會實作 ICorProfilerCallback3，它就是 2.0 版程式碼剖析工具。 在這種情況下，CLR 會釋放程式碼剖析工具介面，而且不會啟動程式碼剖析工具。 不過，CLR 不會卸載程式碼剖析工具 DLL，因此它可以維持與 .NET Framework 2.0 版 CLR 的回溯相容性，而不會卸載程式碼剖析工具 DLL (請注意，.NET Framework 4 程式碼剖析工具會在中斷連結或關閉時卸載，因此如果您要修訂 .NET Framework 4 的程式碼剖析工具，就必須變更這個行為)。

  • PreventLoad

    .NET Framework 4 CLR 會完全忽略程式碼剖析工具。 對於某些同處理序並存案例而言，這項設定很有用。 如需詳細資訊，請參閱同處理序並存程式碼剖析。

例如，若要指示 CLR 載入 .NET Framework 2.0 程式碼剖析工具，請開啟 [命令提示字元] 視窗並輸入下列命令：

set COMPLUS_ProfAPI_ProfilerCompatibilitySetting=EnableV2Profiler
注意事項注意事項

這個相容性參數只會影響程式碼剖析工具啟動路徑。若為附加載入程式碼剖析工具，執行階段就會針對 ICorProfilerCallback3 介面呼叫 IUnknown::QueryInterface 函式。如果程式碼剖析工具不會實作此介面 (適用於 2.0 版程式碼剖析工具)，執行階段就不會載入程式碼剖析工具，而將程式碼剖析工具載入失敗項目記錄在事件記錄檔中。

請參閱

概念

分析概觀

其他資源

.NET Framework 4 中的程式碼剖析

Unmanaged API 參考