Application Insights für ASP.NET Core-Anwendungen

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

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

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

Es wird eine MVC-Beispielanwendung verwendet. Wenn Sie den Workerdienst verwenden, befolgen Sie die hier angegebenen Anweisungen.

Hinweis

Eine Vorschau zum OpenTelemetry-basierten .NET-Angebot ist verfügbar. Weitere Informationen.

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.

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 VM, Docker, Azure Kubernetes Service (AKS) usw.
  • .NET Core-Version: Alle offiziell unterstützten .NET Core-Versionen, die sich nicht in der Vorschauphase befinden
  • IDE: Visual Studio, Visual Studio Code oder Befehlszeile

Hinweis

Voraussetzungen

  • 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.
  • 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 und dann Weiter aus.

  4. Wählen Sie Ihr Abonnement und Ihre Application Insights-Instanz aus (oder erstellen Sie eine neue Instanz mit Neu erstellen), und wählen Sie dann Weiter aus.

  5. Fügen Sie die Verbindungszeichenfolge zu Application Insights hinzu oder bestätigen Sie sie (diese sollte auf der Grundlage Ihrer Auswahl im vorherigen Schritt vorausgefüllt sein), und wählen Sie dann 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 Elemente 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 startup.cs- oder program.cs-Klasse hinzu (abhängig von Ihrer .NET Core-Version).

    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. Einrichten der Verbindungszeichenfolge

    Sie können eine Verbindungszeichenfolge zwar als Teil des Arguments ApplicationInsightsServiceOptions für AddApplicationInsightsTelemetry bereitstellen, doch es wird empfohlen, 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"
      }
    }
    

    Geben Sie alternativ die Verbindungszeichenfolge in der Umgebungsvariablen „APPLICATIONINSIGHTS_CONNECTION_STRING“ oder „ApplicationInsights:ConnectionString“ in der JSON-Konfigurationsdatei an.

    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 Azure-Web-Apps verwendet, 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. Beispiel: services.AddApplicationInsightsTelemetry(Configuration);. Ab Version 2.15.0 von Microsoft.ApplicationInsights.AspNetCore wird durch Aufrufen von services.AddApplicationInsightsTelemetry() automatisch die Verbindungszeichenfolge aus 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 Application Insights-Überwachung ordnungsgemäß konfiguriert ist. Es kann einige Minuten dauern, bis Telemetriedaten im Portal und in der Analyse angezeigt werden. Livemetriken zeigen die CPU-Auslastung des laufenden Prozesses jedoch nahezu in Echtzeit an. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten und Ablaufverfolgungen angezeigt werden.

ILogger-Protokolle

Die Standardkonfiguration sammelt ILogger-Protokolle mit dem Schweregrad Warning und höher. Weitere Informationen finden Sie unter Wie passe ich die Sammlung von ILogger-Protokollen an?

Abhängigkeiten

Die Abhängigkeitssammlung ist standardmäßig aktiviert. In diesem Artikel werden die Abhängigkeiten, die automatisch gesammelt werden, sowie die Schritte zur manuellen Nachverfolgung erläutert.

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 Azure-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 das .NET Framework bestimmt sind, werden Leistungsindikatoren in allen Versionen des SDK unterstützt.
  • Die SDK-Versionen 2.8.0 und höher unterstützen Leistungsindikatoren für CPU und Arbeitsspeicher unter Linux. Es werden kein weiteren Leistungsindikatoren unter Linux unterstützt. Die empfohlene Vorgehensweise für Systemleistungsindikatoren unter Linux (und in anderen Nicht-Windows-Umgebungen) ist die Verwendung von 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, sollten Sie die unten angegebenen Schritte ausführen, um mit dem Erfassen von Nutzungstelemetriedaten zu beginnen.

  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 der JavaScript-Codeausschnitt im <head>-Abschnitt jeder Anwendungsseite vorhanden sein, die Sie überwachen möchten. Fügen Sie den JavaScript-Codeausschnitt zu _Layout.cshtml in einer Anwendungsvorlage 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 den JavaScript-Codeausschnitt einer entsprechenden Datei hinzufügen, die den <head>-Abschnitt aller Seiten in Ihrer App steuert. Alternativ können Sie den Codeausschnitt mehreren Seiten hinzufügen, doch wird das 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 oben 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 QuickPulse (Live Metrics stream).
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 true
EnableAdaptiveSampling Adaptive Stichprobenerstellung aktivieren/deaktivieren true
EnableHeartbeat 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. true
AddAutoCollectedMetricExtractor 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. true
RequestCollectionOptions.TrackExceptions Berichterstellung über die Nachverfolgung von Ausnahmefehlern durch das Anforderungserfassungsmodul aktivieren/deaktivieren. In NETSTANDARD2.0 „false“ (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

Ab Version 2.15.0 des Microsoft.ApplicationInsights.AspNetCore-SDK wird die Konfiguration aller in ApplicationInsightsServiceOptions verfügbaren Einstellungen empfohlen, einschließlich ConnectionString unter Verwendung der 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 um zusätzliche Informationen erweitern 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. Ansonsten ist Folgendes erforderlich: builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" });

Entfernen von TelemetryInitializer-Elementen

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 von Telemetrieprozessoren

Sie können TelemetryConfiguration benutzerdefinierte Telemetrieprozessoren hinzufügen, indem Sie die Erweiterungsmethode AddApplicationInsightsTelemetryProcessor in IServiceCollection verwenden. Telemetrieprozessoren werden in komplexen Filterszenarien verwendet. Verwenden 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 TelemetryModule-Standardelementen

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 RequestTelemetry von eingehenden Webanfragen
  • DependencyTrackingTelemetryModule: Sammelt Abhängigkeitstelemetriedaten (DependencyTelemetry) aus ausgehenden HTTP-Aufrufen und SQL-Aufrufen
  • PerformanceCollectorModule: Sammelt Windows-Leistungsindikatoren PerformanceCounters
  • QuickPulseTelemetryModule: Sammelt Telemetriedaten zur Anzeige im Live Metriken-Portal
  • AppServicesHeartbeatTelemetryModule: Sammelt Heartbeats (die als benutzerdefinierte Metriken gesendet werden) über die Azure 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 EventCounters. Dieses Modul ist ein neues Feature und in der SDK-Version 2.8.0 und höher verfügbar

Verwenden Sie zum Konfigurieren von TelemetryModule-Standardelementen 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

Siehe Leerdaten, wenn Sie den Puffer leeren wollen – 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

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

Ja. Führen Sie ein Update auf Application Insights SDK für ASP.NET Core Version 2.8.0 oder höher durch. In älteren Versionen des SDK wird ASP.NET Core 3.X nicht unterstützt.

Wenn Sie serverseitige Telemetrie für Visual Studio aktivieren, führen Sie außerdem für das Onboarding ein Update auf Visual Studio 2019 (16.3.0) aus. In früheren Versionen von Visual Studio wird das automatische Onboarding für ASP.NET Core 3.X-Apps nicht unterstützt.

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

Rufen Sie eine Instanz von TelemetryClient ab, indem Sie die Abhängigkeit über den Konstruktor übergeben (Constructor Injection) und die erforderliche TrackXXX()-Methode aufrufen. Es wird nicht empfohlen, neue TelemetryClient- oder TelemetryConfiguration-Instanzen in einer ASP.NET Core-Anwendung zu erstellen. Eine Singletoninstanz von TelemetryClient ist bereits im DependencyInjection-Container 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 passe ich die Sammlung von ILogger-Protokollen an?

Standardmäßig werden nur Protokolle mit dem Schweregrad Warning und höher automatisch gesammelt. Um dieses Verhalten zu ändern, überschreiben Sie explizit die Protokollierungskonfiguration für den Anbieter ApplicationInsights, wie unten gezeigt. Mit der folgenden Konfiguration kann Application Insights alle Protokolle mit dem Schweregrad Information und höher sammeln.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

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. Zum Aktivieren von Application Insights-Telemetriedaten wird die Verwendung von AddApplicationInsightsTelemetry() empfohlen, da sie Ü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, werden keine Schritte ausgeführt, 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:

  • Die Application Insights-Telemetriefunktion funktioniert weiterhin
    • 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.
    • mit allen Hostserveroptionen einschließlich Web-Apps, VMs, Linux, Containern, Azure Kubernetes Service und anderer Hostinglösungen als Azure.
    • mit allen .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:

  • Unter Linux sammelt das SDK EventCounters, da Leistungsindikatoren nur unter Windows unterstützt werden. Die meisten Metriken sind identisch.
  • Obwohl 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. Aufgrund dieser Einschränkung gehen Telemetriedaten verloren, wenn vorübergehende Netzwerk- oder Serverprobleme auftreten. Sie können das Problem umgehen, indem Sie einen lokalen Ordner für den Kanal konfigurieren:
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

var builder = WebApplication.CreateBuilder(args);

// 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.
builder.Services.AddSingleton(typeof(ITelemetryChannel),
                        new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Diese Einschränkung gilt ab Version 2.15.0 nicht.

Wird dieses SDK für die neuen .NET Core 3.X Worker Service-Vorlagenanwendungen unterstützt?

Dieses SDK erfordert HttpContext. Daher funktioniert es nicht in Nicht-HTTP-Anwendungen, einschließlich der .NET Core 3.X Worker Service-Anwendungen. Informationen zum Aktivieren von Application Insights in solchen Anwendungen mithilfe des neu veröffentlichten Microsoft.ApplicationInsights.WorkerService-SDK finden Sie unter Application Insights für Workerdienstanwendungen (Anwendungen ohne HTTP).

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

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

Nächste Schritte