Application Insights für ASP.NET Core-AnwendungenApplication Insights for ASP.NET Core applications

In diesem Artikel wird beschrieben, wie Sie Application Insights für eine ASP.NET Core-Anwendung aktivieren.This article describes how to enable Application Insights for an ASP.NET Core application. Nach Abschluss der Schritte in diesem Artikel erfasst Application Insights Anforderungen, Abhängigkeiten, Ausnahmen, Leistungsindikatoren, Heartbeats und Protokolle für Ihre ASP.NET Core-Anwendung.When you complete the instructions in this article, Application Insights will collect requests, dependencies, exceptions, performance counters, heartbeats, and logs from your ASP.NET Core application.

Sie verwenden im folgenden Beispiel eine MVC-Anwendung für netcoreapp3.0.The example we'll use here is an MVC application that targets netcoreapp3.0. Die Anleitung in diesem Artikel können Sie allerdings für alle ASP.NET Core-Anwendungen nutzen.You can apply these instructions to all ASP.NET Core applications. Wenn Sie den Workerdienst verwenden, befolgen Sie die hier angegebenen Anweisungen.If you are using the Worker Service, use the instructions from here.

Unterstützte SzenariosSupported scenarios

Mit dem Application Insights SDK für ASP.NET Core können Sie Anwendungen unabhängig davon überwachen, wo und wie sie ausgeführt werden.The Application Insights SDK for ASP.NET Core can monitor your applications no matter where or how they run. Wenn Ihre Anwendung ausgeführt wird und über eine Netzwerkverbindung mit Azure verfügt, können Telemetriedaten erfasst werden.If your application is running and has network connectivity to Azure, telemetry can be collected. Die Application Insights-Überwachung wird in allen Umgebungen unterstützt, in denen auch .NET Core unterstützt wird.Application Insights monitoring is supported everywhere .NET Core is supported. Dazu zählen:Support covers:

  • Betriebssystem: Windows, Linux oder Mac.Operating system: Windows, Linux, or Mac.
  • Hostingmethode: In-Process oder Out-of-Process.Hosting method: In process or out of process.
  • Bereitstellungsmethode: Abhängig vom Framework oder eigenständig.Deployment method: Framework dependent or self-contained.
  • Webserver: IIS (Internet Information Server) oder Kestrel.Web server: IIS (Internet Information Server) or Kestrel.
  • Hostingplattform: Beispielsweise das Web-Apps-Feature von Azure App Service, Azure Virtual Machines, Docker oder Azure Kubernetes Service (AKS).Hosting platform: The Web Apps feature of Azure App Service, Azure VM, Docker, Azure Kubernetes Service (AKS), and so on.
  • .NET Core-Runtimeversion: 1.XX, 2.XX oder 3.XX.NET Core Runtime version: 1.XX, 2.XX, or 3.XX
  • IDE: Visual Studio, VS Code oder Befehlszeile.IDE: Visual Studio, VS Code, or command line.

Hinweis

ASP.NET Core 3.X erfordert Application Insights 2.8.0 oder höher.ASP.NET Core 3.X requires Application Insights 2.8.0 or later.

VoraussetzungenPrerequisites

  • Eine funktionierende ASP.NET Core-Anwendung.A functioning ASP.NET Core application. Wenn Sie eine ASP.NET Core-Anwendung erstellen müssen, führen Sie die Schritte im entsprechenden ASP.NET Core-Tutorial aus.If you need to create an ASP.NET Core application, follow this ASP.NET Core tutorial.
  • Ein gültiger Application Insights-Instrumentierungsschlüssel.A valid Application Insights instrumentation key. Dieser ist erforderlich, um Telemetriedaten an Application Insights zu senden.This key is required to send any telemetry to Application Insights. Wenn Sie eine neue Application Insights-Ressource erstellen müssen, um einen Instrumentierungsschlüssel abzurufen, finden Sie unter Erstellen einer Application Insights-Ressource weitere Informationen.If you need to create a new Application Insights resource to get an instrumentation key, see Create an Application Insights resource.

Aktivieren der serverseitigen Telemetrie für Application Insights (Visual Studio)Enable Application Insights server-side telemetry (Visual Studio)

  1. Öffnen Sie Ihr Projekt in Visual Studio.Open your project in Visual Studio.

    Tipp

    Sie können bei Bedarf die Quellcodeverwaltung für Ihr Projekt einrichten, sodass alle Änderungen erfasst werden, die Application Insights vornimmt.If you want to, you can set up source control for your project so you can track all the changes that Application Insights makes. Klicken Sie auf Datei > Zur Quellcodeverwaltung hinzufügen, um die Quellcodeverwaltung zu aktivieren.To enable source control, select File > Add to Source Control.

  2. Wählen Sie Projekt > Application Insights-Telemetrie hinzufügen aus.Select Project > Add Application Insights Telemetry.

  3. Wählen Sie Erste Schritte aus.Select Get Started. Je nach verwendeter Version von Visual Studio kann der Text des Steuerelements abweichen.This selection's text might vary, depending on your version of Visual Studio. Bei einigen älteren Versionen wird stattdessen die Schaltfläche Kostenlos starten angezeigt.Some earlier versions use a Start Free button instead.

  4. Wählen Sie Ihr Abonnement aus.Select your subscription. Klicken Sie dann auf Ressource > Registrieren.Then select Resource > Register.

  5. Überprüfen Sie nach dem Hinzufügen von Application Insights zu Ihrem Projekt, ob Sie das neueste stabile Release des SDK verwenden.After adding Application Insights to your project, check to confirm that you're using the latest stable release of the SDK. Wechseln Sie zu Projekt > NuGet-Pakete verwalten > Microsoft.ApplicationInsights.AspNetCore.Go to Project > Manage NuGet Packages > Microsoft.ApplicationInsights.AspNetCore. Klicken Sie bei Bedarf auf Aktualisieren.If you need to, choose Update.

    Screenshot: Auswahl des Application Insights-Pakets, das aktualisiert werden soll

  6. Wenn Sie den optionalen Tipp umgesetzt und für Ihr Projekt die Quellcodeverwaltung aktiviert haben, wechseln Sie zu Ansicht > Team Explorer > Änderungen.If you followed the optional tip and added your project to source control, go to View > Team Explorer > Changes. Klicken Sie dann auf eine Datei, um sich eine Vergleichsansicht für Änderungen anzeigen zu lassen, die vom Application Insights-Telemetriefeature vorgenommen wurden.Then select each file to see a diff view of the changes made by Application Insights telemetry.

Aktivieren der serverseitigen Telemetrie für Application Insights (ohne Visual Studio)Enable Application Insights server-side telemetry (no Visual Studio)

  1. Installieren Sie das Application Insights SDK-NuGet-Paket für ASP.NET Core.Install the Application Insights SDK NuGet package for ASP.NET Core. Sie sollten immer die neueste stabile Version verwenden.We recommend that you always use the latest stable version. Vollständige Versionshinweise für das SDK finden Sie im Open-Source-GitHub-Repository.Find full release notes for the SDK on the open-source GitHub repo.

    Im folgenden Beispielcode wird gezeigt, welche Elemente Sie der .csproj-Datei Ihres Projekts hinzufügen müssen.The following code sample shows the changes to be added to your project's .csproj file.

        <ItemGroup>
          <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.13.1" />
        </ItemGroup>
    
  2. Fügen Sie wie im folgenden Beispiel dargestellt services.AddApplicationInsightsTelemetry(); der ConfigureServices()-Methode in Ihrer Startup-Klasse hinzu:Add services.AddApplicationInsightsTelemetry(); to the ConfigureServices() method in your Startup class, as in this example:

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // The following line enables Application Insights telemetry collection.
            services.AddApplicationInsightsTelemetry();
    
            // This code adds other services for your application.
            services.AddMvc();
        }
    
  3. Richten Sie den Instrumentierungsschlüssel ein.Set up the instrumentation key.

    Sie können einen Instrumentierungsschlüssel als Argument für AddApplicationInsightsTelemetry bereitstellen. Empfohlen wird aber, den Instrumentierungsschlüssel in der Konfiguration anzugeben.Although you can provide the instrumentation key as an argument to AddApplicationInsightsTelemetry, we recommend that you specify the instrumentation key in configuration. Im folgenden Beispielcode wird veranschaulicht, wie Sie in appsettings.json einen Instrumentierungsschlüssel angeben.The following code sample shows how to specify an instrumentation key in appsettings.json. Stellen Sie sicher, dass appsettings.json während der Veröffentlichung in den Stammordner der Anwendung kopiert wird.Make sure appsettings.json is copied to the application root folder during publishing.

        {
          "ApplicationInsights": {
            "InstrumentationKey": "putinstrumentationkeyhere"
          },
          "Logging": {
            "LogLevel": {
              "Default": "Warning"
            }
          }
        }
    

    Alternativ können Sie den Instrumentierungsschlüssel auch in einer der folgenden Umgebungsvariablen angeben:Alternatively, specify the instrumentation key in either of the following environment variables:

    • APPINSIGHTS_INSTRUMENTATIONKEY

    • ApplicationInsights:InstrumentationKey

    Beispiel:For example:

    • SET ApplicationInsights:InstrumentationKey=putinstrumentationkeyhere

    • SET APPINSIGHTS_INSTRUMENTATIONKEY=putinstrumentationkeyhere

    • APPINSIGHTS_INSTRUMENTATIONKEY wird in der Regel in Azure-Web-Apps verwendet, kann aber auch an allen Stellen verwendet werden, an denen dieses SDK unterstützt wird.APPINSIGHTS_INSTRUMENTATIONKEY is typically used in Azure Web Apps, but can also be used in all places where this SDK is supported. (Wenn Sie eine Überwachung von Web-Apps ohne Code durchführen, ist dieses Format erforderlich, wenn Sie keine Verbindungszeichenfolgen verwenden.)(If you are doing codeless web app monitoring, this format is required if you aren't using connection strings.)

    Anstatt Instrumentierungsschlüssel festzulegen, können Sie jetzt auch Verbindungszeichenfolgen verwenden.In lieu of setting instrumentation keys you can now also use Connection Strings.

    Hinweis

    Ein Instrumentierungsschlüssel, der im Code angegeben ist, erhält Vorrang vor der Umgebungsvariable APPINSIGHTS_INSTRUMENTATIONKEY, die wiederum Vorrang vor anderen Optionen hat.An instrumentation key specified in code wins over the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, which wins over other options.

Ausführen der AnwendungRun your application

Führen Sie Ihre Anwendung aus, und senden Sie Anforderungen an diese.Run your application and make requests to it. Nun sollten Telemetriedaten an Application Insights übermittelt werden.Telemetry should now flow to Application Insights. Mit dem Application Insights SDK werden eingehende Webanforderungen an die Anwendung sowie die folgenden Telemetriedaten automatisch erfasst.The Application Insights SDK automatically collects incoming web requests to your application, along with the following telemetry as well.

LivemetrikenLive Metrics

Mit Livemetriken kann schnell überprüft werden, ob die Application Insights-Überwachung ordnungsgemäß konfiguriert ist.Live Metrics can be used to quickly verify if Application Insights monitoring is configured correctly. Es kann einige Minuten dauern, bis die Telemetriedaten im Portal und in der Analyse angezeigt werden. In Livemetriken wird die CPU-Auslastung des laufenden Prozesses dagegen nahezu in Echtzeit angezeigt.While it might take a few minutes before telemetry starts appearing in the portal and analytics, Live Metrics would show CPU usage of the running process in near real-time. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten oder Ablaufverfolgungen angezeigt werden.It can also show other telemetry like Requests, Dependencies, Traces, etc.

ILogger-ProtokolleILogger logs

Protokolle, die über ILogger mit dem Schweregrad Warning oder höher ausgegeben werden, werden automatisch erfasst.Logs emitted via ILogger of severity Warning or greater are automatically captured. Informationen zur Anpassung der in Application Insights erfassten Protokollebenen finden Sie in der Dokumentation zu ILogger.Follow ILogger docs to customize which log levels are captured by Application Insights.

AbhängigkeitenDependencies

Die Abhängigkeitssammlung ist standardmäßig aktiviert.Dependency collection is enabled by default. In diesem Artikel werden die Abhängigkeiten, die automatisch gesammelt werden, sowie die Schritte zur manuellen Nachverfolgung erläutert.This article explains the dependencies that are automatically collected, and also contain steps to do manual tracking.

LeistungsindikatorenPerformance counters

Für die Unterstützung von Leistungsindikatoren in ASP.NET Core gelten die folgenden Einschränkungen:Support for performance counters in ASP.NET Core is limited:

  • Die SDK-Versionen 2.4.1 und höher erfassen Leistungsindikatoren, wenn die Anwendung in Azure-Web-Apps (Windows) ausgeführt wird.SDK versions 2.4.1 and later collect performance counters if the application is running in Azure Web Apps (Windows).
  • Die SDK-Versionen 2.7.1 und höher erfassen Leistungsindikatoren, wenn die Anwendung unter Windows läuft und NETSTANDARD2.0 oder höher als Zielframework verwendet wird.SDK versions 2.7.1 and later collect performance counters if the application is running in Windows and targets NETSTANDARD2.0 or later.
  • Für Anwendungen, die für das .NET Framework bestimmt sind, werden Leistungsindikatoren in allen Versionen des SDK unterstützt.For applications targeting the .NET Framework, all versions of the SDK support performance counters.
  • Die SDK-Versionen 2.8.0 und höher unterstützen Leistungsindikatoren für CPU und Arbeitsspeicher unter Linux.SDK Versions 2.8.0 and later support cpu/memory counter in Linux. Es werden kein weiteren Leistungsindikatoren unter Linux unterstützt.No other counter is supported in Linux. Die empfohlene Vorgehensweise für Systemleistungsindikatoren unter Linux (und in anderen Nicht-Windows-Umgebungen) ist die Verwendung von EventCounters.The recommended way to get system counters in Linux (and other non-Windows environments) is by using EventCounters

EventCounterEventCounter

EventCounterCollectionModule ist standardmäßig aktiviert und sammelt einen Standardsatz von Leistungsindikatoren von .NET Core 3.X-Apps.EventCounterCollectionModule is enabled by default, and it will collect a default set of counters from .NET Core 3.X apps. Im Tutorial zu EventCounter ist der Standardsatz der gesammelten Leistungsindikatoren aufgeführt.The EventCounter tutorial lists the default set of counters collected. Außerdem enthält es Anweisungen zum Anpassen der Liste.It also has instructions on customizing the list.

Aktivieren der clientseitigen Telemetrie für WebanwendungenEnable client-side telemetry for web applications

Wenn Sie die vorherigen Schritte ausgeführt haben, können Sie serverseitige Telemetriedaten erfassen.The preceding steps are enough to help you start collecting server-side telemetry. Wenn Ihre Anwendung über clientseitige Komponenten verfügt, sollten Sie die unten angegebenen Schritte ausführen, um mit dem Erfassen von Nutzungstelemetriedaten zu beginnen.If your application has client-side components, follow the next steps to start collecting usage telemetry.

  1. Nehmen Sie in _ViewImports.cshtml eine Einfügung vor:In _ViewImports.cshtml, add injection:

        @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    
  2. Fügen Sie in _Layout.cshtml am Ende des <head>-Abschnitts HtmlHelper vor allen anderen Skripts ein.In _Layout.cshtml, insert HtmlHelper at the end of the <head> section but before any other script. Wenn Sie benutzerdefinierte JavaScript-Telemetriedaten für die Seite übermitteln möchten, müssen Sie den Code dafür nach diesem Ausschnitt einfügen:If you want to report any custom JavaScript telemetry from the page, inject it after this snippet:

        @Html.Raw(JavaScriptSnippet.FullScript)
        </head>
    

Alternativ zur Verwendung von FullScript ist ab SDK v2.14 ScriptBody verfügbar.Alternatively to using the FullScript the ScriptBody is available starting in SDK v2.14. Verwenden Sie dieses Element, wenn Sie das <script>-Tag so steuern müssen, dass eine Inhaltssicherheitsrichtlinie festgelegt wird:Use this if you need to control the <script> tag to set a Content Security Policy:

 <script> // apply custom changes to this script tag.
     @Html.Raw(JavaScriptSnippet.ScriptBody)
 </script>

Die .cshtml-Dateinamen, auf die vorher verwiesen wurde, stammen aus der Standardvorlage für MVC-Anwendungen.The .cshtml file names referenced earlier are from a default MVC application template. Wenn Sie die clientseitige Überwachung für Ihre Anwendung ordnungsgemäß aktivieren möchten, muss der JavaScript-Codeausschnitt im <head>-Abschnitt jeder Anwendungsseite vorhanden sein, die Sie überwachen möchten.Ultimately, if you want to properly enable client-side monitoring for your application, the JavaScript snippet must appear in the <head> section of each page of your application that you want to monitor. Für diese Anwendungsvorlage müssen Sie dazu den JavaScript-Codeausschnitt _Layout.cshtml hinzufügen.You can accomplish this goal for this application template by adding the JavaScript snippet to _Layout.cshtml.

Sie können für Ihr Projekt die clientseitige Überwachung auch dann aktivieren, wenn dieses nicht _Layout.cshtml enthält.If your project doesn't include _Layout.cshtml, you can still add client-side monitoring. Fügen Sie hierzu den JavaScript-Codeausschnitt einer entsprechenden Datei hinzu, die den <head>-Abschnitt aller Seiten Ihrer App steuert.You can do this by adding the JavaScript snippet to an equivalent file that controls the <head> of all pages within your app. Sie können den Codeausschnitt auch mehreren Seiten hinzufügen. Diese Lösung lässt sich allerdings auf Dauer nur schwierig umsetzen und wird daher nicht empfohlen.Or you can add the snippet to multiple pages, but this solution is difficult to maintain and we generally don't recommend it.

Konfigurieren des Application Insights SDKConfigure the Application Insights SDK

Sie können die Standardkonfiguration des Application Insights SDK für ASP.NET Core anpassen.You can customize the Application Insights SDK for ASP.NET Core to change the default configuration. Benutzer des ASP.NET SDK für Application Insights können die Konfiguration über ApplicationInsights.config oder durch das Ändern von TelemetryConfiguration.Active anpassen.Users of the Application Insights ASP.NET SDK might be familiar with changing configuration by using ApplicationInsights.config or by modifying TelemetryConfiguration.Active. Wenn Sie die Konfiguration für ASP.NET Core anpassen möchten, müssen Sie anders vorgehen.You change configuration differently for ASP.NET Core. Fügen Sie das ASP.NET Core SDK der Anwendung hinzu, und konfigurieren Sie es mithilfe des integrierten Dependency-Injection-Systems von ASP.NET Core.Add the ASP.NET Core SDK to the application and configure it by using ASP.NET Core built-in dependency injection. Falls nicht anders angegeben, sollten Sie alle Konfigurationsänderungen in der ConfigureServices()-Methode Ihrer Startup.cs-Klasse vornehmen.Make almost all configuration changes in the ConfigureServices() method of your Startup.cs class, unless you're directed otherwise. Weitere Informationen finden Sie in den folgenden Abschnitten.The following sections offer more information.

Hinweis

In ASP.NET Core-Anwendungen wird die Konfiguration durch Änderung von TelemetryConfiguration.Active nicht unterstützt.In ASP.NET Core applications, changing configuration by modifying TelemetryConfiguration.Active isn't supported.

Verwenden von ApplicationInsightsServiceOptionsUsing ApplicationInsightsServiceOptions

Sie können wie im folgenden Beispiel einige allgemeine Einstellungen ändern, indem Sie der AddApplicationInsightsTelemetry-Methode ApplicationInsightsServiceOptions übergeben:You can modify a few common settings by passing ApplicationInsightsServiceOptions to AddApplicationInsightsTelemetry, as in this example:

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

Vollständige Liste der Einstellungen in ApplicationInsightsServiceOptionsFull List of settings in ApplicationInsightsServiceOptions

EinstellungSetting BESCHREIBUNGDescription StandardDefault
EnablePerformanceCounterCollectionModuleEnablePerformanceCounterCollectionModule PerformanceCounterCollectionModule aktivieren/deaktivierenEnable/Disable PerformanceCounterCollectionModule truetrue
EnableRequestTrackingTelemetryModuleEnableRequestTrackingTelemetryModule RequestTrackingTelemetryModule aktivieren/deaktivierenEnable/Disable RequestTrackingTelemetryModule truetrue
EnableEventCounterCollectionModuleEnableEventCounterCollectionModule EventCounterCollectionModule aktivieren/deaktivierenEnable/Disable EventCounterCollectionModule truetrue
EnableDependencyTrackingTelemetryModuleEnableDependencyTrackingTelemetryModule DependencyTrackingTelemetryModule aktivieren/deaktivierenEnable/Disable DependencyTrackingTelemetryModule truetrue
EnableAppServicesHeartbeatTelemetryModuleEnableAppServicesHeartbeatTelemetryModule AppServicesHeartbeatTelemetryModule aktivieren/deaktivierenEnable/Disable AppServicesHeartbeatTelemetryModule truetrue
EnableAzureInstanceMetadataTelemetryModuleEnableAzureInstanceMetadataTelemetryModule AzureInstanceMetadataTelemetryModule aktivieren/deaktivierenEnable/Disable AzureInstanceMetadataTelemetryModule truetrue
EnableQuickPulseMetricStreamEnableQuickPulseMetricStream „LiveMetrics“-Feature aktivieren/deaktivierenEnable/Disable LiveMetrics feature truetrue
EnableAdaptiveSamplingEnableAdaptiveSampling Adaptive Stichprobenerstellung aktivieren/deaktivierenEnable/Disable Adaptive Sampling truetrue
EnableHeartbeatEnableHeartbeat Heartbeats-Feature aktivieren/deaktivieren, das in regelmäßigen Abständen (Standardwert: 15 Minuten) eine benutzerdefinierte Metrik namens „HeartbeatState“ mit Informationen zur Laufzeit wie .NET-Version, ggf. Informationen zur Azure-Umgebung usw. sendet.Enable/Disable Heartbeats feature, which periodically (15-min default) sends a custom metric named 'HeartbeatState' with information about the runtime like .NET Version, Azure Environment information, if applicable, etc. truetrue
AddAutoCollectedMetricExtractorAddAutoCollectedMetricExtractor Extraktor für „AutoCollectedMetrics“ aktivieren/deaktivieren, bei dem es sich um einen Telemetrieprozessor handelt, der vorab aggregierte Metriken zu Anforderungen/Abhängigkeiten sendet, bevor die Stichprobenerstellung stattfindet.Enable/Disable AutoCollectedMetrics extractor, which is a TelemetryProcessor that sends pre-aggregated metrics about Requests/Dependencies before sampling takes place. truetrue
RequestCollectionOptions.TrackExceptionsRequestCollectionOptions.TrackExceptions Berichterstellung über die Nachverfolgung von Ausnahmefehlern durch das Anforderungserfassungsmodul aktivieren/deaktivieren.Enable/Disable reporting of unhandled Exception tracking by the Request collection module. In NETSTANDARD2.0 „false“ (da Ausnahmen mit „ApplicationInsightsLoggerProvider“ nachverfolgt werden), andernfalls „true“.false in NETSTANDARD2.0 (because Exceptions are tracked with ApplicationInsightsLoggerProvider), true otherwise.

Die aktuelle Liste finden Sie unter den konfigurierbaren Einstellungen in ApplicationInsightsServiceOptions.See the configurable settings in ApplicationInsightsServiceOptions for the most up-to-date list.

StichprobenSampling

Das Application Insights SDK für ASP.NET Core unterstützt sowohl die feste als auch die adaptive Stichprobenerstellung.The Application Insights SDK for ASP.NET Core supports both fixed-rate and adaptive sampling. Die adaptive Stichprobenerstellung ist standardmäßig aktiviert.Adaptive sampling is enabled by default.

Weitere Informationen finden Sie unter Konfigurieren der adaptiven Stichprobenerstellung für ASP.NET Core-Anwendungen.For more information, see Configure adaptive sampling for ASP.NET Core applications.

Hinzufügen von TelemetryInitializersAdding TelemetryInitializers

Verwenden Sie Telemetrieinitialisierer, wenn Sie Telemetriedaten um zusätzliche Informationen erweitern möchten.Use telemetry initializers when you want to enrich telemetry with additional information.

Fügen Sie wie im folgenden Code gezeigt dem DependencyInjection-Container einen neuen TelemetryInitializer hinzu.Add any new TelemetryInitializer to the DependencyInjection container as shown in the following code. Das SDK erfasst automatisch alle TelemetryInitializer, die dem DependencyInjection-Container hinzugefügt werden.The SDK automatically picks up any TelemetryInitializer that's added to the DependencyInjection container.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

Entfernen von TelemetryInitializer-ElementenRemoving TelemetryInitializers

Telemetrieinitialisierer sind standardmäßig vorhanden.Telemetry initializers are present by default. Wenn Sie alle oder nur bestimmte Telemetrieinitialisierer entfernen möchten, können Sie den folgenden Beispielcode nach dem Aufrufen von AddApplicationInsightsTelemetry() verwenden.To remove all or specific telemetry initializers, use the following sample code after you call AddApplicationInsightsTelemetry().

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // Remove a specific built-in telemetry initializer
    var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                        (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
    if (tiToRemove != null)
    {
        services.Remove(tiToRemove);
    }

    // Remove all initializers
    // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
    services.RemoveAll(typeof(ITelemetryInitializer));
}

Hinzufügen von TelemetrieprozessorenAdding telemetry processors

Sie können TelemetryConfiguration benutzerdefinierte Telemetrieprozessoren hinzufügen, indem Sie die Erweiterungsmethode AddApplicationInsightsTelemetryProcessor in IServiceCollection verwenden.You can add custom telemetry processors to TelemetryConfiguration by using the extension method AddApplicationInsightsTelemetryProcessor on IServiceCollection. Telemetrieprozessoren werden in komplexen Filterszenarien verwendet.You use telemetry processors in advanced filtering scenarios. Verwenden Sie das folgende Beispiel.Use the following example.

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

Konfigurieren oder Entfernen von TelemetryModule-StandardelementenConfiguring or removing default TelemetryModules

Application Insights verwendet Telemetriemodule, um automatisch nützliche Telemetriedaten zu bestimmten Workloads zu erfassen, ohne dass eine manuelle Nachverfolgung durch den Benutzer erforderlich ist.Application Insights uses telemetry modules to automatically collect useful telemetry about specific workloads without requiring manual tracking by user.

Die unten aufgeführten Module sind standardmäßig aktiviert.The following automatic-collection modules are enabled by default. Diese sind verantwortlich für die automatische Erfassung von Telemetriedaten.These modules are responsible for automatically collecting telemetry. Sie können sie deaktivieren oder ihr Standardverhalten anpassen.You can disable or configure them to alter their default behavior.

  • RequestTrackingTelemetryModule: Erfasst Anforderungstelemetriedaten (RequestTelemetry) von eingehenden Webanforderungen.RequestTrackingTelemetryModule - Collects RequestTelemetry from incoming web requests.
  • DependencyTrackingTelemetryModule: Erfasst Abhängigkeitstelemetriedaten (DependencyTelemetry) von ausgehenden HTTP-Aufrufen und SQL-Aufrufen.DependencyTrackingTelemetryModule - Collects DependencyTelemetry from outgoing http calls and sql calls.
  • PerformanceCollectorModule: Erfasst Windows-Leistungsindikatoren (PerformanceCounters).PerformanceCollectorModule - Collects Windows PerformanceCounters.
  • QuickPulseTelemetryModule: Erfasst Telemetriedaten zur Anzeige im Live Metrics-Portal.QuickPulseTelemetryModule - Collects telemetry for showing in Live Metrics portal.
  • AppServicesHeartbeatTelemetryModule: Erfasst Heartbeats (die als benutzerdefinierte Metriken gesendet werden) über die Azure App Service-Umgebung, in der die Anwendung gehostet wird.AppServicesHeartbeatTelemetryModule - Collects heart beats (which are sent as custom metrics), about Azure App Service environment where application is hosted.
  • AzureInstanceMetadataTelemetryModule: Erfasst Heartbeats (die als benutzerdefinierte Metriken gesendet werden) über die Azure-VM-Umgebung, in der die Anwendung gehostet wird.AzureInstanceMetadataTelemetryModule - Collects heart beats (which are sent as custom metrics), about Azure VM environment where application is hosted.
  • EventCounterCollectionModule: Erfasst EventCounters.EventCounterCollectionModule - Collects EventCounters. Dieses Modul ist ein neues Feature, das ab SDK-Version 2.8.0 verfügbar ist.This module is a new feature and is available in SDK Version 2.8.0 and higher.

Verwenden Sie zum Konfigurieren von TelemetryModule-Standardelementen die Erweiterungsmethode ConfigureTelemetryModule<T> in IServiceCollection. Dies ist im Beispiel unten dargestellt.To configure any default TelemetryModule, use the extension method ConfigureTelemetryModule<T> on IServiceCollection, as shown in the following example.

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // The following configures DependencyTrackingTelemetryModule.
    // Similarly, any other default modules can be configured.
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
            {
                module.EnableW3CHeadersInjection = true;
            });

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                module.Counters.Clear();
                module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
            }
        );

    // The following removes PerformanceCollectorModule to disable perf-counter collection.
    // Similarly, any other default modules can be removed.
    var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

Ab Version 2.12.2 enthält ApplicationInsightsServiceOptions die einfache Option zum Deaktivieren der Standardmodule.Starting with 2.12.2 version, ApplicationInsightsServiceOptions contains easy option to disable any of the default modules.

Konfigurieren eines TelemetriekanalsConfiguring a telemetry channel

Der standardmäßige Telemetriekanal ist ServerTelemetryChannel.The default telemetry channel is ServerTelemetryChannel. Sie können diesen wie im folgenden Beispiel dargestellt überschreiben.You can override it as the following example shows.

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetry();
    }

Dynamisches Deaktivieren von TelemetrieDisable telemetry dynamically

Wenn Sie Telemetriedaten bedingt und dynamisch deaktivieren möchten, können Sie eine TelemetryConfiguration-Instanz mit einem ASP.NET Core-Dependency-Injection-Container an einer beliebigen Stelle im Code auflösen und ein DisableTelemetry-Flag dafür festlegen.If you want to disable telemetry conditionally and dynamically, you may resolve TelemetryConfiguration instance with ASP.NET Core dependency injection container anywhere in your code and set DisableTelemetry flag on it.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetry();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Durch den oben genannten Vorgang wird nicht verhindert, dass Telemetriedaten von Modulen für die automatische Erfassung gesammelt werden.The above does not prevent any auto collection modules from collecting telemetry. Nur das Senden von Telemetriedaten an Application Insights wird mit der oben beschriebenen Methode deaktiviert.Only the sending of telemetry to Application Insights gets disabled with the above approach. Wenn ein bestimmtes Modul für die automatische Sammlung nicht gewünscht wird, ist es am besten, das Telemetriemodul zu entfernen.If a particular auto collection module is not desired, it is best to remove the telemetry module

Häufig gestellte FragenFrequently asked questions

Wird ASP.NET Core 3.X in Application Insights unterstützt?Does Application Insights support ASP.NET Core 3.X?

Ja.Yes. Führen Sie ein Update auf Application Insights SDK für ASP.NET Core Version 2.8.0 oder höher durch.Update to Application Insights SDK for ASP.NET Core version 2.8.0 or higher. In älteren Versionen des SDK wird ASP.NET Core 3.X nicht unterstützt.Older versions of the SDK do not support ASP.NET Core 3.X.

Wenn Sie die hier beschriebenen Anweisungen zu Visual Studio befolgen, führen Sie ein Update auf die neueste Version von Visual Studio 2019 (16.3.0) durch, um das Onboarding durchzuführen.Also, if you are using Visual Studio based instructions from here, update to the latest version of Visual Studio 2019 (16.3.0) to onboard. In früheren Versionen von Visual Studio wird das automatische Onboarding für ASP.NET Core 3.X-Apps nicht unterstützt.Previous versions of Visual Studio do not support automatic onboarding for ASP.NET Core 3.X apps.

Wie kann ich Telemetriedaten nachverfolgen, die nicht automatisch erfasst werden?How can I track telemetry that's not automatically collected?

Rufen Sie eine Instanz von TelemetryClient ab, indem Sie die Abhängigkeit über den Konstruktor übergeben (Constructor Injection) und die erforderliche TrackXXX()-Methode aufrufen.Get an instance of TelemetryClient by using constructor injection, and call the required TrackXXX() method on it. Nicht empfohlen wird das Erstellen neuer TelemetryClient-Instanzen in einer ASP.NET Core-Anwendung.We don't recommend creating new TelemetryClient instances in an ASP.NET Core application. Eine Singletoninstanz von TelemetryClient ist bereits im DependencyInjection-Container registriert, der TelemetryConfiguration für alle sonstigen Telemetriedaten verwendet.A singleton instance of TelemetryClient is already registered in the DependencyInjection container, which shares TelemetryConfiguration with rest of the telemetry. Sie sollten nur dann eine neue TelemetryClient-Instanz erstellen, wenn für diese eine Konfiguration erforderlich ist, die sich von der für die sonstigen Telemetriedaten unterscheidet.Creating a new TelemetryClient instance is recommended only if it needs a configuration that's separate from the rest of the telemetry.

Im folgenden Beispiel wird veranschaulicht, wie Sie zusätzliche Telemetrie über einen Controller nachverfolgen.The following example shows how to track additional telemetry from a controller.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Wie Sie Daten in Application Insights benutzerdefiniert erfassen können, erfahren Sie unter Application Insights-API für benutzerdefinierte Ereignisse und Metriken.For more information about custom data reporting in Application Insights, see Application Insights custom metrics API reference. Ein ähnlicher Ansatz kann verwendet werden, um mithilfe der GetMetric-API benutzerdefinierte Metriken an Application Insights zu senden.A similar approach can be used for sending custom metrics to Application Insights using the GetMetric API.

Für einige Visual Studio-Vorlagen wurde die Erweiterungsmethode „UseApplicationInsights()“ in IWebHostBuilder verwendet, um Application Insights zu aktivieren.Some Visual Studio templates used the UseApplicationInsights() extension method on IWebHostBuilder to enable Application Insights. Ist diese Verwendung noch gültig?Is this usage still valid?

Obwohl die Erweiterungsmethode UseApplicationInsights() weiterhin unterstützt wird, ist sie ab Application Insights SDK Version 2.8.0 als veraltet markiert.While the extension method UseApplicationInsights() is still supported, it is marked obsolete in Application Insights SDK version 2.8.0 onwards. Sie wird in der nächsten Hauptversion des SDK entfernt.It will be removed in the next major version of the SDK. Die empfohlene Vorgehensweise zur Aktivierung von Application Insights-Telemetriedaten ist die Verwendung von AddApplicationInsightsTelemetry(), da so Überladungen zum Steuern einiger Konfigurationen möglich sind.The recommended way to enable Application Insights telemetry is by using AddApplicationInsightsTelemetry() because it provides overloads to control some configuration. In ASP.NET Core 3.X-Apps ist services.AddApplicationInsightsTelemetry() außerdem die einzige Möglichkeit zum Aktivieren von Application Insights.Also, in ASP.NET Core 3.X apps, services.AddApplicationInsightsTelemetry() is the only way to enable application insights.

Ich stelle meine ASP.NET Core-Anwendung in Web-Apps bereit.I'm deploying my ASP.NET Core application to Web Apps. Sollte ich trotzdem die Application Insights-Erweiterung über Web-Apps aktivieren?Should I still enable the Application Insights extension from Web Apps?

Wenn das SDK wie in diesem Artikel gezeigt zur Buildzeit installiert wird, ist es nicht erforderlich, die Application Insights-Erweiterung über das App Service-Portal zu aktivieren.If the SDK is installed at build time as shown in this article, you don't need to enable the Application Insights extension from the App Service portal. Auch bei installierter Erweiterung werden keine Schritte ausgeführt, wenn erkannt wird, dass das SDK der Anwendung bereits hinzugefügt wurde.Even if the extension is installed, it will back off when it detects that the SDK is already added to the application. Wenn Sie Application Insights über die Erweiterung aktivieren, müssen Sie das SDK nicht installieren und aktualisieren.If you enable Application Insights from the extension, you don't have to install and update the SDK. Wenn Sie Application Insights jedoch mithilfe der Anweisungen in diesem Artikel aktivieren, sind Sie aus den folgenden Gründen flexibler:But if you enable Application Insights by following instructions in this article, you have more flexibility because:

  • Die Application Insights-Telemetriefunktion funktioniert weiterhinApplication Insights telemetry will continue to work in:
    • auf allen Betriebssystemen einschließlich Windows, Linux und Mac.All operating systems, including Windows, Linux, and Mac.
    • mit allen Veröffentlichungsmodi einschließlich dem eigenständigen oder frameworkabhängigen Modus.All publish modes, including self-contained or framework dependent.
    • allen Zielframeworks, z. B. vollständigem .NET Framework.All target frameworks, including the full .NET Framework.
    • mit allen Hostserveroptionen einschließlich Web-Apps, VMs, Linux, Containern, Azure Kubernetes Service und anderer Hostinglösungen als Azure.All hosting options, including Web Apps, VMs, Linux, containers, Azure Kubernetes Service, and non-Azure hosting.
    • mit allen .NET Core-Versionen, einschließlich Vorschauversionen.All .NET Core versions including preview versions.
  • Sie können Telemetriedaten lokal beim Debuggen in Visual Studio anzeigen.You can see telemetry locally when you're debugging from Visual Studio.
  • Sie können mit der TrackXXX()-API zusätzliche benutzerdefinierte Telemetriedaten nachverfolgen.You can track additional custom telemetry by using the TrackXXX() API.
  • Die vollständige Steuerung der Konfiguration ist Ihnen überlassen.You have full control over the configuration.

Kann ich die Application Insights-Überwachung mit Tools wie dem Statusmonitor aktivieren?Can I enable Application Insights monitoring by using tools like Status Monitor?

Nein.No. Der Statusmonitor und der Statusmonitor v2 unterstützen aktuell ausschließlich ASP.NET 4.x.Status Monitor and Status Monitor v2 currently support ASP.NET 4.x only.

Ist Application Insights für meine ASP.NET Core 2.0-Anwendung automatisch aktiviert?Is Application Insights automatically enabled for my ASP.NET Core 2.0 application?

Im Microsoft.AspNetCore.All 2.0-Metapaket ist das Application Insights SDK (Version 2.1.0) enthalten.The Microsoft.AspNetCore.All 2.0 metapackage included the Application Insights SDK (version 2.1.0). Wenn Sie die Anwendung im Visual Studio-Debugger ausführen, wird Application Insights von Visual Studio aktiviert, und die Telemetriedaten werden lokal in der IDE angezeigt.If you run the application under Visual Studio debugger, Visual Studio enables Application Insights and shows telemetry locally in the IDE itself. Telemetriedaten werden nicht an Application Insights gesendet, falls nicht explizit ein Instrumentierungsschlüssel angegeben wird.Telemetry wasn't sent to the Application Insights service unless an instrumentation key was specified. Wir empfehlen Ihnen, die Anleitungen in diesem Artikel zu befolgen, um Application Insights zu aktivieren (auch für 2.0-Apps).We recommend following the instructions in this article to enable Application Insights, even for 2.0 apps.

Werden alle Features unterstützt, wenn ich meine Anwendung unter Linux ausführe?If I run my application in Linux, are all features supported?

Ja.Yes. Die Featureunterstützung für das SDK ist auf allen Plattformen gleich. Es gelten lediglich die folgenden Ausnahmen:Feature support for the SDK is the same in all platforms, with the following exceptions:

  • Unter Linux sammelt das SDK EventCounters, da Leistungsindikatoren nur unter Windows unterstützt werden.The SDK collects Event Counters on Linux because Performance Counters are only supported in Windows. Die meisten Metriken sind identisch.Most metrics are the same.
  • Auch wenn ServerTelemetryChannel standardmäßig aktiviert ist, wird über den Kanal bei der Anwendungsausführung unter Linux oder macOS nicht automatisch ein lokaler Speicherordner erstellt, um die Telemetriedaten bei Netzwerkproblemen vorübergehend zu speichern.Even though ServerTelemetryChannel is enabled by default, if the application is running in Linux or MacOS, the channel doesn't automatically create a local storage folder to keep telemetry temporarily if there are network issues. Aufgrund dieser Einschränkung gehen Telemetriedaten verloren, wenn vorübergehende Netzwerk- oder Serverprobleme auftreten.Because of this limitation, telemetry is lost when there are temporary network or server issues. Sie können das Problem umgehen, indem Sie einen lokalen Ordner für den Kanal konfigurieren:To work around this issue, configure a local folder for the channel:
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

    public void ConfigureServices(IServiceCollection services)
    {
        // The following will configure the channel to use the given folder to temporarily
        // store telemetry items during network or Application Insights server issues.
        // User should ensure that the given folder already exists
        // and that the application has read/write permissions.
        services.AddSingleton(typeof(ITelemetryChannel),
                                new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
        services.AddApplicationInsightsTelemetry();
    }

Wird dieses SDK für die neuen .NET Core 3.X Worker Service-Vorlagenanwendungen unterstützt?Is this SDK supported for the new .NET Core 3.X Worker Service template applications?

Dieses SDK erfordert HttpContext und kann daher nicht in Nicht-HTTP-Anwendungen ausgeführt werden, dazu gehören z. B. auch .NET Core 3.X Worker Service-Anwendungen.This SDK requires HttpContext, and hence does not work in any non-HTTP applications, including the .NET Core 3.X Worker Service applications. Informationen zum Aktivieren von Application Insights in diesen Anwendungen unter Verwendung des neu veröffentlichten SDK Microsoft.ApplicationInsights.WorkerService finden Sie hier.Refer to this document for enabling application insights in such applications, using the newly released Microsoft.ApplicationInsights.WorkerService SDK.

Open Source SDKOpen-source SDK

Informationen zu den neuesten Updates und Fehlerbehebungen finden Sie in den Versionshinweisen.For the latest updates and bug fixes consult the release notes.

Nächste SchritteNext steps