Freigeben über

Application Insights für ASP.NET Core-Anwendungen

  • Artikel

In diesem Artikel wird beschrieben, wie Sie Application Insights für eine ASP.NET Core-Anwendung aktivieren und konfigurieren.

Hinweis

Die folgende Dokumentation basiert auf der klassischen Application Insights-API. Der langfristige Plan für Application Insights besteht darin, Daten mithilfe von OpenTelemetry zu sammeln. Weitere Informationen finden Sie unter Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python- und Java-Anwendungen und unserer OpenTelemetry Roadmap. Migrationsleitfaden sind für .NET, Node.js und Python verfügbar.

Application Insights kann die folgenden Telemetriedaten aus Ihrer ASP.NET Core-Anwendung erfassen:

  • Requests
  • Abhängigkeiten
  • Ausnahmen
  • Leistungsindikatoren
  • Heartbeats
  • Protokolle

Wir verwenden eine MVC-Beispielanwendung. Wenn Sie den Worker Service verwenden, verwenden Sie die Anweisungen unter Application Insights für Worker Service-Anwendungen.

Ein OpenTelemetry-basierten .NET-Angebot ist verfügbar. Weitere Informationen finden Sie in der Übersicht über OpenTelemetry.

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

Hinweis

Wenn Sie einen eigenständigen ILogger-Anbieter verwenden möchten, verwenden Sie Microsoft.Extensions.Logging.ApplicationInsight.

Unterstützte Szenarios

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. Wenn Ihre Anwendung ausgeführt wird und über eine Netzwerkverbindung mit Azure verfügt, können Telemetriedaten erfasst werden. Die Überwachung durch Application Insights wird überall unterstützt, wo .NET Core unterstützt wird, und deckt die folgenden Szenarien ab:

  • Betriebssystem: Windows, Linux oder Mac
  • Hostingmethode: Prozessintern oder prozessextern
  • Bereitstellungsmethode: Abhängig vom Framework oder eigenständig
  • Webserver: IIS (Internetinformationsdienste) oder Kestrel
  • Hostingplattform: Das Web-Apps-Feature von Azure App Service, Azure Virtual Machines, Docker und Azure Kubernetes Service (AKS)
  • .NET-Version: Alle offiziell unterstützten .NET-Versionen, die sich nicht in der Vorschauphase befinden
  • IDE: Visual Studio, Visual Studio Code oder Befehlszeile

Voraussetzungen

Erforderlich:

  • Eine funktionierende ASP.NET Core-Anwendung. Wenn Sie eine ASP.NET Core-Anwendung erstellen müssen, führen Sie die Schritte im entsprechenden ASP.NET Core-Tutorial aus.
  • Ein Verweis auf eine unterstützte Version des Application Insights-NuGet-Pakets.
  • Eine gültige Application Insights-Verbindungszeichenfolge. Diese Zeichenfolge ist erforderlich, um Telemetriedaten an Application Insights zu senden. Wenn Sie eine neue Application Insights-Ressource erstellen müssen, um eine Verbindungszeichenfolge abzurufen, finden Sie unter Erstellen einer Application Insights-Ressource weitere Informationen.

Aktivieren der serverseitigen Telemetrie für Application Insights (Visual Studio)

Verwenden Sie für Visual Studio für Mac den Leitfaden für manuelles Aktivieren. Dieses Verfahren wird nur von der Windows-Version von Visual Studio unterstützt.

  1. Öffnen Sie Ihr Projekt in Visual Studio.

  2. Wechseln Sie zu Projekt>Application Insights-Telemetrie hinzufügen.

  3. Wählen Sie Azure Application Insights>Weiter aus.

  4. Wählen Sie Ihr Abonnement und Ihre Application Insights-Instanz aus. Oder Sie können mit Neue erstellen eine neue Instanz erstellen. Wählen Sie Weiter aus.

  5. Fügen Sie Ihre Application Insights-Verbindungszeichenfolge hinzu oder bestätigen Sie sie. Sie sollte basierend auf Ihrer Auswahl im vorherigen Schritt vorgefüllt sein. Wählen Sie Fertig stellen aus.

  6. Überprüfen Sie nach dem Hinzufügen von Application Insights zu Ihrem Projekt, ob Sie das neueste stabile Release des SDK verwenden. Wechseln Sie zu Projekt>NuGet-Pakete verwalten>Microsoft.ApplicationInsights.AspNetCore. Bei Bedarf wählen Sie Aktualisieren aus.

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

Aktivieren der serverseitigen Telemetrie für Application Insights (ohne Visual Studio)

  1. Installieren Sie das Application Insights SDK-NuGet-Paket für ASP.NET Core.

    Sie sollten immer die neueste stabile Version verwenden. Vollständige Versionshinweise für das SDK finden Sie im Open-Source-GitHub-Repository.

    Im folgenden Beispielcode wird gezeigt, welche Änderungen Sie der .csproj-Datei Ihres Projekts hinzufügen müssen:

    <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>

  2. Fügen Sie AddApplicationInsightsTelemetry() zu Ihrer Klasse startup.cs oder program.cs hinzu. Die Auswahl hängt von Ihrer .NET Core-Version ab.

    Fügen Sie wie im folgenden Beispiel dargestellt builder.Services.AddApplicationInsightsTelemetry(); hinter der WebApplication.CreateBuilder()-Methode in Ihrer Program-Klasse hinzu:

    // This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

  3. Richten Sie die Verbindungszeichenfolge ein.

    Sie können eine Verbindungszeichenfolge als Teil des Arguments ApplicationInsightsServiceOptions für AddApplicationInsightsTelemetry bereitstellen. Empfohlen wird aber, die Verbindungszeichenfolge in der Konfiguration anzugeben. Im folgenden Beispielcode wird veranschaulicht, wie Sie in appsettings.json eine Verbindungszeichenfolge angeben. Stellen Sie sicher, dass appsettings.json während der Veröffentlichung in den Stammordner der Anwendung kopiert wird.

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}

    Alternativ können Sie die Verbindungszeichenfolge auch in der Umgebungsvariablen APPLICATIONINSIGHTS_CONNECTION_STRING oder in der JSON-Konfigurationsdatei ApplicationInsights:ConnectionString angeben.

    Beispiel:

    • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
    • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
    • APPLICATIONINSIGHTS_CONNECTION_STRING wird in der Regel in Web-Apps verwendet. Sie kann aber auch überall verwendet werden, wo dieses SDK unterstützt wird.

    Hinweis

    Eine Verbindungszeichenfolge, die im Code angegeben ist, erhält Vorrang vor der Umgebungsvariablen APPLICATIONINSIGHTS_CONNECTION_STRING, die wiederum Vorrang vor anderen Optionen hat.

Benutzergeheimnisse und andere Konfigurationsanbieter

Wenn Sie die Verbindungszeichenfolge in ASP.NET Core-Benutzergeheimnissen speichern oder von einem anderen Konfigurationsanbieter abrufen möchten, können Sie die Überladung mit einem Parameter Microsoft.Extensions.Configuration.IConfiguration verwenden. Ein Beispielparameter ist services.AddApplicationInsightsTelemetry(Configuration);.

In Microsoft.ApplicationInsights.AspNetCore Version 2.15.0 und später wird beim Aufruf von services.AddApplicationInsightsTelemetry() automatisch die Verbindungszeichenfolge aus der Microsoft.Extensions.Configuration.IConfiguration der Anwendung gelesen. IConfiguration muss nicht explizit angegeben werden.

Wenn IConfiguration die Konfiguration von mehreren Anbietern geladen hat, bevorzugt services.AddApplicationInsightsTelemetry die Konfiguration von appsettings.json, unabhängig von der Reihenfolge, in der Anbieter hinzugefügt werden. Verwenden Sie die Methode services.AddApplicationInsightsTelemetry(IConfiguration), um die Konfiguration aus IConfiguration ohne diese bevorzugte Behandlung für appsettings.json zu lesen.

Ausführen der Anwendung

Führen Sie Ihre Anwendung aus, und senden Sie Anforderungen an diese. Nun sollten Telemetriedaten an Application Insights übermittelt werden. Mit dem Application Insights SDK werden eingehende Webanforderungen an die Anwendung sowie die folgenden Telemetriedaten automatisch erfasst.

Livemetriken

Mit Livemetriken kann schnell überprüft werden, ob die Anwendungsüberwachung mit Application Insights ordnungsgemäß konfiguriert ist. Es kann einige Minuten dauern, bis Telemetriedaten im Azure-Portal angezeigt werden. Im Bereich „Livemetriken“ wird jedoch die CPU-Auslastung des laufenden Prozesses nahezu in Echtzeit angezeigt. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten und Ablaufverfolgungen angezeigt werden.

Aktivieren von Livemetriken für beliebige .NET-Anwendungen mithilfe von Code

Hinweis

Livemetriken sind standardmäßig aktiviert, wenn sie deren Onboarding gemäß den empfohlenen Anweisungen für .NET-Anwendungen durchführen.

So konfigurieren Sie Livemetriken manuell

  1. Installieren Sie das NuGet-Paket Microsoft.ApplicationInsights.PerfCounterCollector.
  2. Im Folgenden finden Sie Beispielcode für die Konsolen-App zum Einrichten von Livemetriken:
using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

Auch wenn das obige Beispiel für eine Konsolen-App vorgesehen ist, kann derselbe Code doch in allen .NET-Anwendungen verwendet werden. Wenn weitere Telemetriemodule zum automatischen Erfassen von Telemetriedaten aktiviert sind, sollten Sie dafür sorgen, dass dieselbe Konfiguration, mit der diese Module initialisiert wurden, auch für das Livemetriken-Modul verwendet wird.

ILogger-Protokolle

Die Standardkonfiguration sammelt ILogger-Protokolle mit dem Schweregrad Warning und höher. Weitere Informationen finden Sie unter Anpassen der Sammlung von ILogger-Protokollen.

Abhängigkeiten

Die Abhängigkeitssammlung ist standardmäßig aktiviert. Im Artikel Abhängigkeitsnachverfolgung in Application Insights werden die Abhängigkeiten erläutert, die automatisch erfasst werden. Außerdem finden Sie dort Schritte zur manuellen Nachverfolgung.

Leistungsindikatoren

Für die Unterstützung von Leistungsindikatoren in ASP.NET Core gelten die folgenden Einschränkungen:

  • Die SDK-Versionen 2.4.1 und höher erfassen Leistungsindikatoren, wenn die Anwendung in Web-Apps (Windows) ausgeführt wird.
  • 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.
  • Für Anwendungen, die für .NET Framework bestimmt sind, werden Leistungsindikatoren in allen Versionen des SDK unterstützt.
  • SDK-Versionen ab 2.8.0 unterstützen Leistungsindikatoren für CPU und Arbeitsspeicher unter Linux. Es werden kein weiteren Leistungsindikatoren unter Linux unterstützt. Zum Abrufen von Systemleistungsindikatoren unter Linux (und in anderen Nicht-Windows-Umgebungen) dient EventCounters.

EventCounter

EventCounterCollectionModule ist standardmäßig aktiviert. Informationen zum Konfigurieren der Liste der zu sammelnden Leistungsindikatoren finden Sie unter Einführung in EventCounters.

Anreichern von Daten über HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Aktivieren der clientseitigen Telemetrie für Webanwendungen

Wenn Sie die vorherigen Schritte ausgeführt haben, können Sie serverseitige Telemetriedaten erfassen. Wenn Ihre Anwendung über clientseitige Komponenten verfügt, führen Sie die folgenden Schritte aus, um mit der Erfassung von Nutzungstelemetriedaten zu beginnen. Die Einschleusung des JavaScript (Web) SDK-Ladeprogrammskripts erfolgt über die Konfiguration.

  1. Nehmen Sie in _ViewImports.cshtml eine Einfügung vor:

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

  2. Fügen Sie in _Layout.cshtml am Ende des <head>-Abschnitts HtmlHelper vor allen anderen Skripts ein. Wenn Sie benutzerdefinierte JavaScript-Telemetriedaten für die Seite übermitteln möchten, müssen Sie den Code dafür nach diesem Ausschnitt einfügen:

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

Als Alternative zur Verwendung von FullScript ist ab Version 2.14 des Application Insights SDK für ASP.NET Core ScriptBody verfügbar. Verwenden Sie ScriptBody, wenn Sie das <script>-Tag so steuern müssen, dass eine Inhaltssicherheitsrichtlinie festgelegt wird:

<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. Wenn Sie die clientseitige Überwachung für Ihre Anwendung ordnungsgemäß aktivieren möchten, muss das JavaScript (Web) SDK Loader-Skript im <head>-Abschnitt jeder Seite Ihrer Anwendung, die Sie überwachen möchten, vorhanden sein. Fügen Sie das JavaScript (Web) SDK Loader-Skript in einer Anwendungsvorlage zu _Layout.cshtml hinzu, um die clientseitige Überwachung zu aktivieren.

Wenn Ihr Projekt _Layout.cshtml nicht enthält, können Sie trotzdem die clientseitige Überwachung hinzufügen, indem Sie das JavaScript (Web) SDK Loader-Skript einer entsprechenden Datei hinzufügen, die den <head>-Abschnitt aller Seiten in Ihrer Anwendung steuert. Alternativ können Sie das JavaScript (Web) SDK Loader-Skript mehreren Seiten hinzufügen, dies wird jedoch nicht empfohlen.

Hinweis

Die JavaScript-Einschleusung bietet eine Standardkonfigurationserfahrung. Wenn Sie eine Konfiguration benötigen, die über das Festlegen der Verbindungszeichenfolge hinausgeht, müssen Sie die automatische Einschleusung wie beschrieben entfernen und das JavaScript SDK manuell hinzufügen.

Konfigurieren des Application Insights SDK

Sie können die Standardkonfiguration des Application Insights SDK für ASP.NET Core anpassen. Benutzer des ASP.NET SDK für Application Insights können die Konfiguration über ApplicationInsights.config oder durch das Ändern von TelemetryConfiguration.Active anpassen. Falls nicht anders angegeben, werden fast alle Konfigurationsänderungen für ASP.NET Core in der ConfigureServices()-Methode Ihrer Startup.cs-Klasse vorgenommen. Weitere Informationen finden Sie in den folgenden Abschnitten.

Hinweis

In ASP.NET Core-Anwendungen wird die Konfiguration durch Änderung von TelemetryConfiguration.Active nicht unterstützt.

Verwenden von ApplicationInsightsServiceOptions

Sie können wie im folgenden Beispiel einige allgemeine Einstellungen ändern, indem Sie der AddApplicationInsightsTelemetry-Methode ApplicationInsightsServiceOptions übergeben:

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

Diese Tabelle enthält die vollständige Liste der ApplicationInsightsServiceOptions-Einstellungen:

Einstellung BESCHREIBUNG Standard
EnablePerformanceCounterCollectionModule PerformanceCounterCollectionModule aktivieren/deaktivieren. True
EnableRequestTrackingTelemetryModule RequestTrackingTelemetryModule aktivieren/deaktivieren. True
EnableEventCounterCollectionModule EventCounterCollectionModule aktivieren/deaktivieren. True
EnableDependencyTrackingTelemetryModule DependencyTrackingTelemetryModule aktivieren/deaktivieren. True
EnableAppServicesHeartbeatTelemetryModule AppServicesHeartbeatTelemetryModule aktivieren/deaktivieren. True
EnableAzureInstanceMetadataTelemetryModule AzureInstanceMetadataTelemetryModule aktivieren/deaktivieren. True
EnableQuickPulseMetricStream „LiveMetrics“-Feature aktivieren/deaktivieren Richtig
EnableAdaptiveSampling Aktivieren/Deaktivieren der adaptiven Stichprobenerstellung True
EnableHeartbeat Aktivieren/Deaktivieren Sie die Funktion „Heartbeats“. Sie sendet in regelmäßigen Abständen (Standardwert: 15 Minuten) eine benutzerdefinierte Metrik namens HeartbeatState mit Informationen zur Runtime wie .NET-Version und ggf. Informationen zur Azure-Umgebung. True
AddAutoCollectedMetricExtractor Aktivieren/Deaktivieren Sie den AutoCollectedMetrics extractor. Dieser Telemetrieprozessor sendet vor der Stichprobenentnahme vorab aggregierte Metriken zu Anforderungen/Abhängigkeiten. True
RequestCollectionOptions.TrackExceptions Aktivieren/deaktivieren Sie die Berichterstellung über die Nachverfolgung von Ausnahmefehlern durch das Anforderungserfassungsmodul. „False“ in netstandard2.0 (da Ausnahmen mit ApplicationInsightsLoggerProvider nachverfolgt werden). Andernfalls „True“.
EnableDiagnosticsTelemetryModule DiagnosticsTelemetryModule aktivieren/deaktivieren. Bei Deaktivierung werden die folgenden Einstellungen ignoriert: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule und EnableAppServicesHeartbeatTelemetryModule. True

Die aktuelle Liste finden Sie unter den konfigurierbaren Einstellungen in ApplicationInsightsServiceOptions.

Konfigurationsempfehlungen für Version 2.15.0 und höher des Microsoft.ApplicationInsights.AspNetCore-SDK

Konfigurieren Sie in Microsoft.ApplicationInsights.AspNetCore SDK, Version 2.15.0 und höher, alle in ApplicationInsightsServiceOptions verfügbaren Einstellungen, einschließlich ConnectionString. Verwenden Sie die IConfiguration-Instanz der Anwendung. Die Einstellungen müssen sich im Abschnitt ApplicationInsights befinden, wie im folgenden Beispiel zu sehen. Im folgenden Abschnitt aus appsettings.json wird die Verbindungszeichenfolge konfiguriert, und die adaptive Stichprobenerstellung und das Sammeln von Leistungsindikatoren werden deaktiviert.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Wenn Sie builder.Services.AddApplicationInsightsTelemetry(aiOptions) für ASP.NET Core 6.0 oder services.AddApplicationInsightsTelemetry(aiOptions) für ASP.NET Core 3.1 und niedriger verwenden, werden die Einstellungen von Microsoft.Extensions.Configuration.IConfiguration außer Kraft gesetzt.

Stichproben

Das Application Insights SDK für ASP.NET Core unterstützt sowohl die feste als auch die adaptive Stichprobenerstellung. Die adaptive Stichprobenerstellung ist standardmäßig aktiviert.

Weitere Informationen finden Sie unter Konfigurieren der adaptiven Stichprobenerstellung für ASP.NET Core-Anwendungen.

Hinzufügen von TelemetryInitializers

Verwenden Sie Telemetrieinitialisierer, wenn Sie Telemetriedaten mit zusätzlichen Informationen anreichern möchten.

Fügen Sie wie im folgenden Code gezeigt dem DependencyInjection-Container einen neuen TelemetryInitializer hinzu. Das SDK erfasst automatisch alle TelemetryInitializer, die dem DependencyInjection-Container hinzugefügt werden.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Hinweis

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); kann für einfache Initialisierer verwendet werden. Für andere ist builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); erforderlich.

Entfernen von Telemetrieinitialisierern

Telemetrieinitialisierer sind standardmäßig vorhanden. Wenn Sie alle oder nur bestimmte Telemetrieinitialisierer entfernen möchten, können Sie den folgenden Beispielcode nach dem Aufrufen von AddApplicationInsightsTelemetry() verwenden.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

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

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

var app = builder.Build();

Hinzufügen Telemetrieprozessoren

Sie können TelemetryConfiguration benutzerdefinierte Telemetrieprozessoren hinzufügen, indem Sie die Erweiterungsmethode AddApplicationInsightsTelemetryProcessor in IServiceCollection verwenden. Telemetrieprozessoren werden in komplexen Filterszenarien verwendet. Nehmen Sie das folgende Beispiel:

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

Konfigurieren oder Entfernen von TelemetryModules

Application Insights erfasst automatisch Telemetriedaten zu bestimmten Workloads, ohne dass eine manuelle Nachverfolgung durch den Benutzer erforderlich ist.

Die unten aufgeführten Module für die automatische Sammlung sind standardmäßig aktiviert. Diese sind verantwortlich für die automatische Erfassung von Telemetriedaten. Sie können sie deaktivieren oder ihr Standardverhalten anpassen.

  • RequestTrackingTelemetryModule: Sammelt Anforderungstelemetriedaten (RequestTelemetry) aus eingehenden Webanforderungen
  • DependencyTrackingTelemetryModule: Sammelt Abhängigkeitstelemetriedaten (DependencyTelemetry) aus ausgehenden HTTP-Aufrufen und SQL-Aufrufen
  • PerformanceCollectorModule: Sammelt Windows-Leistungsindikatoren (PerformanceCounters)
  • QuickPulseTelemetryModule: Sammelt Telemetriedaten, die im Bereich „Livemetriken“ angezeigt werden sollen.
  • AppServicesHeartbeatTelemetryModule: Sammelt Heartbeats (die als benutzerdefinierte Metriken gesendet werden) über die App Service-Umgebung, in der die Anwendung gehostet wird
  • AzureInstanceMetadataTelemetryModule: Sammelt Heartbeats (die als benutzerdefinierte Metriken gesendet werden) über die Azure VM-Umgebung, in der die Anwendung gehostet wird
  • EventCounterCollectionModule: Sammelt Ereignisindikatoren (EventCounters) Dieses Modul ist ein neues Feature, das ab SDK-Version 2.8.0 verfügbar ist.

Verwenden Sie zum Konfigurieren von Standard-TelemetryModule die Erweiterungsmethode ConfigureTelemetryModule<T> in IServiceCollection. Dies ist im Beispiel unten dargestellt:

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

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

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            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 = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

Ab Version 2.12.2 enthält ApplicationInsightsServiceOptions eine Option zum einfachen Deaktivieren beliebiger Standardmodule.

Konfigurieren eines Telemetriekanals

Der standardmäßige Telemetriekanal ist ServerTelemetryChannel. Im folgenden Beispiel wird gezeigt, wie Sie sie überschreiben.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Hinweis

Informationen zum Leeren des Puffers finden Sie unter Leeren von Daten. In einigen Fällen ist es möglicherweise erforderlich, den Puffer zu leeren – beispielsweise bei der Verwendung des SDK in einer Anwendung, die heruntergefahren wird.

Dynamisches Deaktivieren von Telemetrie

Wenn Sie Telemetriedaten bedingt und dynamisch deaktivieren möchten, können Sie eine TelemetryConfiguration-Instanz mit einem ASP.NET Core-Abhängigkeitseinschleusungscontainer an einer beliebigen Stelle im Code auflösen und ein DisableTelemetry-Flag dafür festlegen.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

Das Codebeispiel oben verhindert das Senden von Telemetriedaten an Application Insights. Dadurch wird nicht verhindert, dass Telemetriedaten von Modulen für die automatische Sammlung gesammelt werden. Wenn Sie ein bestimmtes Modul für die automatische Sammlung entfernen möchten, finden Sie weitere Informationen unter Entfernen des Telemetriemoduls.

Häufig gestellte Fragen

Dieser Abschnitt enthält Antworten auf häufig gestellte Fragen.

Wird ASP.NET Core 3.1 in Application Insights unterstützt?

ASP.NET Core 3.1 wird von Microsoft nicht mehr unterstützt.

Application Insights SDK für ASP.NET Core-Version 2.8.0 und Visual Studio 2019 oder höher kann mit ASP.NET Core 3.1-Anwendungen verwendet werden.

Wie kann ich Telemetriedaten nachverfolgen, die nicht automatisch erfasst werden?

Rufen Sie eine Instanz von TelemetryClient ab. Verwenden Sie dazu die Konstruktorinjektion, und rufen Sie die erforderliche TrackXXX()-Methode auf. Es wird nicht empfohlen, neue TelemetryClient- oder TelemetryConfiguration-Instanzen in einer ASP.NET Core-Anwendung zu erstellen. Eine Singletoninstanz von TelemetryClient ist bereits im Container DependencyInjection registriert, der TelemetryConfiguration für alle sonstigen Telemetriedaten verwendet. 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.

Im folgenden Beispiel wird veranschaulicht, wie Sie weitere Telemetriedaten über einen Controller nachverfolgen.

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. Ein ähnlicher Ansatz kann verwendet werden, um mithilfe der GetMetric-API benutzerdefinierte Metriken an Application Insights zu senden.

Wie erfasse ich den Anforderungs- und Antworttext in meinen Telemetriedaten?

ASP.NET Core verfügt über integrierte Unterstützung zum Protokollieren von HTTP-Anforderungs-/Antwortinformationen (einschließlich Text) über ILogger. Es wird empfohlen, diese zu nutzen. Dadurch werden möglicherweise personenbezogene Informationen in den Telemetriedaten verfügbar gemacht, und die Kosten (Leistungskosten und Application Insights-Abrechnung) können erheblich steigen. Wägen Sie daher vor der Nutzung die Risiken sorgfältig ab.

Wie passe ich die Sammlung von ILogger-Protokollen an?

Die Standardeinstellung für Application Insights besteht darin, nur Warnung und schwerwiegendere Protokolle zu erfassen.

Erfassen Sie Informationen und weniger schwerwiegende Protokolle, indem Sie die Protokollierungskonfiguration für den Application Insights-Anbieter wie folgt ändern.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

Beachten Sie unbedingt, dass das folgende Beispiel nicht dazu führt, dass der Application Insights-Anbieter Information-Protokolle sammelt. Sie werden nicht gesammelt, da das SDK einen Standardprotokollierungsfilter hinzufügt, der ApplicationInsights anweist, nur Protokolle mit dem Schweregrad Warning und höher zu sammeln. Application Insights erfordert eine explizite Überschreibung.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Weitere Informationen finden Sie unter ILogger-Konfiguration.

Für einige Visual Studio-Vorlagen wurde die Erweiterungsmethode „UseApplicationInsights()“ in IWebHostBuilder verwendet, um Application Insights zu aktivieren. Ist diese Verwendung noch gültig?

Obwohl die Erweiterungsmethode UseApplicationInsights() weiterhin unterstützt wird, ist sie ab der Application Insights SDK-Version 2.8.0 als veraltet markiert. Sie wird in der nächsten Hauptversion des SDK entfernt. Verwenden Sie zum Aktivieren von Application Insights-Telemetriedaten AddApplicationInsightsTelemetry(), da es Überladungen zum Steuern einiger Konfigurationen bietet. In ASP.NET Core 3.X-Apps ist services.AddApplicationInsightsTelemetry() außerdem die einzige Möglichkeit zum Aktivieren von Application Insights.

Ich stelle meine ASP.NET Core-Anwendung in Web-Apps bereit. Sollte ich trotzdem die Application Insights-Erweiterung über Web-Apps aktivieren?

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. Wenn die Erweiterung installiert ist, erfolgen keine Schritte, sobald erkannt wird, dass das SDK bereits hinzugefügt wurde. Wenn Sie Application Insights über die Erweiterung aktivieren, müssen Sie das SDK nicht installieren und aktualisieren. Wenn Sie Application Insights jedoch mithilfe der Anweisungen in diesem Artikel aktivieren, sind Sie aus den folgenden Gründen flexibler:

  • Application Insights-Telemetrie funktioniert weiterhin in:
    • auf allen Betriebssystemen einschließlich Windows, Linux und Mac.
    • mit allen Veröffentlichungsmodi einschließlich dem eigenständigen oder frameworkabhängigen Modus.
    • allen Zielframeworks, z. B. vollständigem .NET Framework.
    • Alle Hostingoptionen, einschließlich Web-Apps, VMs, Linux, Container, AKS und Nicht-Azure-Hosting.
    • Alle .NET Core-Versionen, einschließlich Vorschauversionen.
  • Sie können Telemetriedaten lokal beim Debuggen in Visual Studio anzeigen.
  • Sie können mit der TrackXXX()-API weitere benutzerdefinierte Telemetriedaten nachverfolgen.
  • Die vollständige Steuerung der Konfiguration ist Ihnen überlassen.

Kann ich die Application Insights-Überwachung mithilfe von Tools wie Azure Monitor Application Insights-Agent (früher Statusmonitor v2) aktivieren?

Ja. Ab Application Insights-Agent 2.0.0-beta1 werden in IIS gehostete ASP.NET Core-Anwendungen unterstützt.

Werden alle Features unterstützt, wenn ich meine Anwendung unter Linux ausführe?

Ja. Die Featureunterstützung für das SDK ist auf allen Plattformen gleich. Es gelten lediglich die folgenden Ausnahmen:

Wird dieses SDK für Workerdienste unterstützt?

Nein Verwenden Sie Application Insights für Workerdienstanwendungen (Nicht-HTTP-Anwendungen) für Workerdienste.

Wie kann ich das SDK deinstallieren?

Zum Entfernen von Application Insights müssen Sie die NuGet-Pakete und -Verweise aus der API in Ihrer Anwendung entfernen. Sie können NuGet-Pakete mithilfe des NuGet-Paket-Managers in Visual Studio deinstallieren.

Hinweis

Diese Anweisungen gelten für die Deinstallation des ASP.NET Core SDK. Wenn Sie das ASP.NET SDK deinstallieren müssen, lesen Sie die Informationen unter Wie kann ich das ASP.NET SDK deinstallieren?.

  1. Deinstallieren Sie das Paket „Microsoft.ApplicationInsights.AspNetCore“ mithilfe des NuGet-Paket-Managers.
  2. Um Application Insights vollständig zu entfernen, müssen Sie den hinzugefügten Code bzw. die hinzugefügten Dateien sowie alle API-Aufrufe, die Sie in Ihrem Projekt hinzugefügt haben, überprüfen und manuell löschen. Weitere Informationen finden Sie unter Was wird erstellt, wenn Sie das Application Insights SDK hinzufügen?.

Beim Hinzufügen von Application Insights SDK erstellte Elemente

Wenn Sie Ihrem Projekt Application Insights hinzufügen, werden Dateien erstellt und einigen Dateien wird Code hinzugefügt. Durch alleiniges Deinstallieren der NuGet-Pakete werden die Dateien und der Code nicht immer gelöscht. Um Application Insights vollständig zu entfernen, sollten Sie den hinzugefügten Code bzw. die hinzugefügten Dateien sowie alle API-Aufrufe, die Sie in Ihrem Projekt hinzugefügt haben, überprüfen und manuell löschen.

Wenn Sie Application Insights-Telemetrie zu einem ASP.NET Core-Vorlagenprojekt in Visual Studio hinzufügen, wird folgender Code hinzugefügt:

  • [Name Ihres Projekts].csproj

      <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

  • Appsettings.json:

    "ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

  • ConnectedService.json

    {
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

  • Startup.cs

       public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

Wie kann ich die Telemetriekorrelation deaktivieren?

Weitere Informationen zum Deaktivieren der Telemetriekorrelation im Code finden Sie unter <ExcludeComponentCorrelationHttpHeadersOnDomains> in Application Insights für Konsolenanwendungen.

Problembehandlung

Informationen finden Sie in dem dedizierten Artikel zur Problembehandlung.

Testen der Konnektivität zwischen Ihrem Anwendungshost und dem Erfassungsdienst

Application Insights SDKs und -Agents senden Telemetriedaten, die als REST-Aufrufe unserer Erfassungsendpunkte erfasst werden sollen. Sie können die Konnektivität Ihres Webservers oder Anwendungshostcomputers mit den Endpunkten des Erfassungsdiensts testen, indem Sie unformatierte REST-Clients über PowerShell- oder cURL-Befehle verwenden. Weitere Informationen finden Sie unter Problembehandlung bei fehlender Anwendungstelemetrie in Azure Monitor Application Insights.

Open Source SDK

Lesen und Hinzufügen von Code.

Informationen zu den neuesten Updates und Fehlerbehebungen finden Sie in den Versionshinweisen.

Versionsinformationen

Versionen ab 2.12: .NET SDKs (einschließlich ASP.NET, ASP.NET Core und Protokollierungsadaptern)

Unser Dienstupdates fassen auch wichtige Application Insights-Verbesserungen zusammen.

Nächste Schritte