使用 ApplicationInsights.config 或 .xml 設定 Application Insights SDK

發行項
10/15/2024

Application Insights .NET SDK 是由許多 NuGet 封裝組成。核心封裝提供 API，用於傳送遙測至 Application Insights。其他套件提供遙測模組和初始設定式，用於自動從您的應用程式和其內容追蹤遙測。調整設定檔，即可啟用或停用遙測模組和初始設定式。您也可以設定其中一些項目的參數。

注意

下列文件以 Application Insights 傳統 API 為依據。 Application Insights 的長期計劃是使用 OpenTelemetry 收集資料。如需詳細資訊，請參閱啟用適用於 .NET、Node.js、Python 和 JAVA 應用程式的 Azure 監視器 OpenTelemetry 和我們的 OpenTelemetry 藍圖。移轉指導適用於 .NET、Node.js 和 Python。

設定檔的名稱為 ApplicationInsights.config 或 ApplicationInsights.xml。名稱取決於應用程式的類型。當您安裝大部分版本的 SDK 時，系統會自動將組態檔新增至您的專案。根據預設，從支援 [新增] > [Application Insights Telemetry] 的 Visual Studio 範本專案使用自動化體驗時，專案根資料夾中會建立 ApplicationInsights.config 檔案。其在編譯時會複製至 bin 資料夾。其還可透過 IIS 伺服器上的 Application Insights 新增到 Web 應用程式中。如果使用 Azure 網站的延伸模組或 Azure VM 和虛擬機器擴展集的延伸模組，則會忽略設定檔。

沒有同等的檔案可控制網頁中的 SDK。

本文說明您在設定檔中看到的內容、控制 SDK 元件的方式，以及哪些 NuGet 套件載入這些元件。

注意

ApplicationInsights.config 和 .xml 指示不適用於 .NET Core SDK。若要設定 .NET Core 應用程式，請遵循適用於 ASP.NET Core 應用程式的 Application Insights 中的指示。

遙測模組 (ASP.NET)

每個遙測模組收集特定類型的資料，以及使用核心 API 來傳送資料。模組由不同的 NuGet 封裝安裝，也會將必要的行加入 .config 檔案。

組態檔中的每個模組都有一個節點。若要停用模組，請刪除節點或將其註解化。

相依性追蹤

相依性追蹤會收集有關您的 app 對資料庫和外部服務和資料庫呼叫的遙測。若要允許此模組用於 IIS 伺服器，您必須安裝 Application Insights 代理程式。

您也可以使用 TrackDependency API 撰寫自己的相依性追蹤程式碼。

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
Microsoft.ApplicationInsights.DependencyCollector NuGet 套件

使用代理程式型 (無程式碼) 連結，即可自動收集相依性，而不需修改您的程式碼。若要使用於 Azure Web 應用程式，請啟用 Application Insights 延伸模組。若要將其用於 Azure VM 或 Azure 虛擬機器擴展集，請啟用 VM 和虛擬機器擴展集的應用程式監視延伸模組。

效能收集器

效能收集器會收集系統效能計數器，例如 IIS 安裝的 CPU、記憶體和網路負載。您可以指定要收集哪些計數器，包括您自己所設定的效能計數器。

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
Microsoft.ApplicationInsights.PerfCounterCollector NuGet 套件

Application Insights 診斷遙測

DiagnosticsTelemetryModule 類別報告 Application Insights 檢測程式碼本身中的錯誤。範例是如果程式碼無法存取效能計數器，或如果 ITelemetryInitializer 擲回例外狀況。此模組所追蹤的追蹤遙測會出現在診斷搜尋中。

Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
Microsoft.ApplicationInsights NuGet 封裝。如果您只安裝這個封裝，不會自動建立 ApplicationInsights.config 檔案。

開發人員模式

DeveloperModeWithDebuggerAttachedTelemetryModule 類別會強制 Application Insights TelemetryChannel 立即傳送資料，以在偵錯工具附加至應用程式程序時一次傳送一個遙測項目。此設計會減少您的應用程式追蹤遙測時與當遙測出現在 Application Insights 入口網站時之間的時間量。但是會造成 CPU 和網路頻寬明顯的負擔。

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
Application Insights Windows Server NuGet 封裝

Web 要求追蹤

Web 要求追蹤會報告 HTTP 要求的回應時間和結果碼。

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
Microsoft.ApplicationInsights.Web NuGet 封裝。

例外狀況追蹤

ExceptionTrackingTelemetryModule 類別追蹤 Web 應用程式中未處理的例外狀況。如需詳細資訊，請參閱失敗和例外狀況。

Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
Microsoft.ApplicationInsights.Web NuGet 套件。
Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule：追蹤未觀察到的工作。例外狀況。
Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule：追蹤背景工作角色、Windows 服務和主控台應用程式的未處理例外狀況。
Application Insights Windows Server NuGet 封裝。

EventSource 追蹤

EventSourceTelemetryModule 類別可讓您設定要傳送至 Application Insights 作為追蹤的 EventSource 事件。如需追蹤 EventSource 事件的相關資訊，請參閱使用 EventSource 事件。

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft.ApplicationInsights.EventSourceListener

ETW 事件追蹤

EtwCollectorTelemetryModule 類別可讓您設定要傳送至 Application Insights 作為追蹤的 ETW 提供者事件。如需追蹤 ETW 事件的相關資訊，請參閱使用 ETW 事件。

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

Microsoft.ApplicationInsights 套件提供 SDK 的核心 API。其他遙測模組使用此 API。您也可以使用其來定義您自己的遙測。

ApplicationInsights.config 中沒有項目。
Microsoft.ApplicationInsights NuGet 封裝。如果您只安裝此 NuGet，不會產生任何 .config 檔案。

遙測通道

遙測通道管理遙測的緩衝處理和到 Application Insights 服務的傳輸。

Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel 是 Web 應用程式的預設通道。其會緩衝處理記憶體中的資料，並採用重試機制和本機磁碟儲存體來提供更可靠的遙測傳遞。
Microsoft.ApplicationInsights.InMemoryChannel 是輕量型遙測通道。其用於未設定其他通道時。

遙測初始設定式 (ASP.NET)

遙測初始設定式設定與遙測的每個項目一起傳送的內容屬性。

您可以撰寫您自己的初始設定式設定內容屬性。

標準初始設定式都是由 Web 或 WindowsServer NuGet 套件所設定：

AccountIdTelemetryInitializer 設定 AccountId 屬性。
AuthenticatedUserIdTelemetryInitializer 會如 JavaScript SDK 設定般設定 AuthenticatedUserId 屬性。
針對具有從 Azure 執行階段環境擷取之資訊的所有遙測項目，AzureRoleEnvironmentTelemetryInitializer 會更新 Device 內容的 RoleName 和 RoleInstance 屬性。
針對具有從 MS 組建所產生之 BuildInfo.config 檔案擷取值的所有遙測項目，BuildInfoConfigComponentVersionTelemetryInitializer 會更新 Component 內容的 Version 屬性。
ClientIpHeaderTelemetryInitializer 會根據要求的 X-Forwarded-For HTTP 標頭來更新所有遙測項目之 Location 內容的 Ip 屬性。
DeviceTelemetryInitializer 會更新所有遙測項目 Device 內容的下列屬性。
- Type 設定為 PC。
- Id 設定為 Web 應用程式執行所在電腦的網域名稱。
- OemName 設定為使用 WMI 從 Win32_ComputerSystem.Manufacturer 欄位擷取的值。
- Model 設定為使用 WMI 從 Win32_ComputerSystem.Model 欄位擷取的值。
- NetworkType 設定為從 NetworkInterface 屬性擷取的值。
- Language 設定為 CurrentCulture 屬性的名稱。
針對具有 Web 應用程式執行所在電腦之網域名稱的所有遙測項目，DomainNameRoleInstanceTelemetryInitializer 會更新 Device 內容的 RoleInstance 屬性。
OperationNameTelemetryInitializer 會根據 HTTP 方法，以及 ASP.NET MVC 控制器的名稱和叫用來處理要求的動作，來更新所有遙測項目 RequestTelemetry 的 Name 屬性和 Operation 內容的 Name 屬性。
OperationIdTelemetryInitializer 或 OperationCorrelationTelemetryInitializer 在處理具有自動產生的 RequestTelemetry.Id 的要求時，會更新追蹤的所有遙測項目的 Operation.Id 內容屬性。
針對具有從使用者瀏覽器中執行的 ApplicationInsights JavaScript 檢測程式碼所產生之 ai_session Cookie 擷取值的所有遙測項目，SessionTelemetryInitializer 會更新 Session 內容的 Id 屬性。
SyntheticTelemetryInitializer 或 SyntheticUserAgentTelemetryInitializer 在處理來自綜合來源 (例如可用性測試或搜尋引擎 Bot) 的要求時，會更新追蹤的所有遙測項目的 User、Session 和 Operation 內容屬性。根據預設，計量瀏覽器不會顯示綜合遙測。

<Filters> 會設定要求的識別屬性。
針對具有從使用者瀏覽器中執行之 Application Insights JavaScript 檢測程式碼所產生的 ai_user Cookie 擷取值的所有遙測項目，UserTelemetryInitializer 會更新 User 內容的 Id 和 AcquisitionDate 屬性。
WebTestTelemetryInitializer 會設定使用者識別碼、工作階段識別碼，以及來自可用性測試的 HTTP 要求的綜合來源屬性。 <Filters> 會設定要求的識別屬性。

針對 Azure Service Fabric 中執行的 .NET 應用程式，您可以包括 Microsoft.ApplicationInsights.ServiceFabric NuGet 套件。此套件所包括的 FabricTelemetryInitializer 屬性會將 Service Fabric 屬性新增至遙測項目。如需詳細資訊，請參閱 GitHub 頁面了解這個 NuGet 套件所新增之屬性的相關資訊。

遙測處理器 (ASP.NET)

遙測處理器可以在遙測從 SDK 傳送至入口網站之前篩選並修改每個遙測項目。

您可以撰寫您自己的遙測處理器。

自適性取樣遙測處理器 (自 2.0.0-beta3 起)

此功能預設為啟用。如果您的應用程式傳送許多遙測，此處理器會移除其中一些遙測。


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

參數會提供演算法嘗試要達成的目標。每個 SDK 執行個體都會獨立運作。因此，如果您的伺服器是數個機器的叢集，則實際遙測數目會隨之加乘。

深入了解取樣。

固定取樣遙測處理器 (自 2.0.0-beta1 起)

還有一種標準取樣遙測處理器 (自 2.0.1 起)：


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

請參閱連接字串程式碼範例。

InstrumentationKey

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

此設定會決定您的資料會在其中顯示的 Application Insights 資源。通常您會針對每個應用程式，使用個別金鑰來建立個別資源。

如果您想要動態設定金鑰 (例如，想要將應用程式的結果傳送至不同的資源)，則可以在設定檔中省略金鑰，並將金鑰設定在程式碼中。

若要設定所有 TelemetryClient 執行個體的金鑰 (包括標準遙測模組)，請在初始化方法中執行此步驟，例如 ASP.NET 服務中的 global.aspx.cs：

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

如果您想要將一組特定事件傳送至不同的資源，則可以針對特定遙測用戶端設定金鑰：


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

若要取得新的金鑰，請在 Application Insights 入口網站中建立新的資源。

ApplicationId 提供者

提供者從 v2.6.0 開始可供使用。

提供者的用途是要查閱以檢測金鑰為基礎的應用程式識別碼。應用程式識別碼包含在 RequestTelemetry 和 DependencyTelemetry 中，並且用來判斷入口網站中的相互關聯。

在程式碼或設定檔中設定 TelemetryConfiguration.ApplicationIdProvider，即可使用此功能。

介面：IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

我們在 Microsoft.ApplicationInsights SDK 中提供兩個實作：ApplicationInsightsApplicationIdProvider 和 DictionaryApplicationIdProvider。

ApplicationInsightsApplicationIdProvider

此包裝函式可用於我們的設定檔 API。它會對要求進行節流處理並快取結果。

當您安裝 Microsoft.ApplicationInsights.DependencyCollector 或 Microsoft.ApplicationInsights.Web 時，此提供者會新增至設定檔。

此類別具有選擇性屬性 ProfileQueryEndpoint。這預設為 https://dc.services.visualstudio.com/api/profiles/{0}/appId。如果您需要設定此設定的 Proxy，則建議對基底位址 (Base Address) 進行 Proxy 處理，並包括 "/api/profiles/{0}/appId"。根據要求，會在執行階段將 {0} 替代為檢測金鑰。

透過 ApplicationInsights.config 的範例設定

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

透過程式碼的範例設定

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

此靜態提供者依賴您所設定的檢測金鑰/應用程式識別碼配對。

此類別具有 Defined 屬性，而此屬性是檢測金鑰/應用程式識別碼配對的 Dictionary<string,string>。

此類別具有選擇性 Next 屬性，可在您的設定中不存在所要求的檢測金鑰時，用來設定其他提供者。

透過 ApplicationInsights.config 的範例設定

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

透過程式碼的範例設定

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

設定 ASP.NET 應用程式的快照集集合

設定 ASP.NET 應用程式的快照集集合。

下一步

深入了解 API

共用方式為

使用 ApplicationInsights.config 或 .xml 設定 Application Insights SDK

遙測模組 (ASP.NET)

相依性追蹤

效能收集器

Application Insights 診斷遙測

開發人員模式

Web 要求追蹤

例外狀況追蹤

EventSource 追蹤

ETW 事件追蹤

Microsoft.ApplicationInsights

遙測通道

遙測初始設定式 (ASP.NET)

遙測處理器 (ASP.NET)

自適性取樣遙測處理器 (自 2.0.0-beta3 起)

固定取樣遙測處理器 (自 2.0.0-beta1 起)

ConnectionString

InstrumentationKey

ApplicationId 提供者

介面：IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

透過 ApplicationInsights.config 的範例設定

透過程式碼的範例設定

DictionaryApplicationIdProvider

透過 ApplicationInsights.config 的範例設定

透過程式碼的範例設定

設定 ASP.NET 應用程式的快照集集合

下一步

意見反應

其他資源