Verwenden des Azure SDK für .NET in ASP.NET Core-Apps

Artikel
11/16/2024

Mit dem Azure SDK für .NET können ASP.NET Core-Apps in viele verschiedene Azure-Dienste integriert werden. In diesem Artikel lernen Sie bewährte Methoden und die Schritte zum Einführen des Azure SDK für .NET in Ihren ASP.NET Core-Apps kennen. Sie lernen Folgendes:

Registrieren Sie Dienste für die Abhängigkeitsinjektion.
Authentifizieren Sie sich bei Azure, ohne Kennwörter oder geheime Schlüssel zu verwenden.
Implementieren Sie zentrale, standardisierte Konfiguration.
Konfigurieren Sie allgemeine Web-App-Bedenken, z. B. Protokollierung und Wiederholungen.

Erkunden allgemeiner Azure SDK-Clientbibliotheken

ASP.NET Core-Apps, die eine Verbindung mit Azure-Diensten herstellen, hängen in der Regel von den folgenden Azure SDK-Clientbibliotheken ab:

Microsoft.Extensions.Azure bietet Hilfsmethoden zum Registrieren von Clients mit der Sammlung des Abhängigkeitseinfügungsdiensts und behandelt verschiedene Bedenken für Sie, z. B. das Einrichten der Protokollierung, die Behandlung von DI-Dienstlebensdauern und die Verwaltung von Anmeldeinformationen.
Azure.Identity ermöglicht die Unterstützung der Microsoft Entra-ID-Authentifizierung im gesamten Azure SDK. Es stellt eine Reihe von TokenCredential-Implementierungen bereit, um Azure SDK-Clients zu erstellen, die die Microsoft Entra-Authentifizierung unterstützen.
Azure.<service-namespace>Bibliotheken, z. B. Azure.Storage.Blobs und Azure.Messaging.ServiceBus, stellen Dienstclients und andere Typen bereit, mit denen Sie eine Verbindung mit bestimmten Azure-Diensten herstellen und nutzen können. Eine vollständige Bestandsaufnahme dieser Bibliotheken finden Sie unter "Bibliotheken mit Azure.Core".

In den folgenden Abschnitten erfahren Sie, wie Sie eine ASP.NET Core-Anwendung implementieren, die diese Bibliotheken verwendet.

Registrieren von Azure SDK-Clients mit der DI-Dienstsammlung

Das Azure SDK für .NET-Clientbibliotheken bieten Dienstclients, um Ihre App mit Azure-Diensten wie Azure Blob Storage und Azure Key Vault zu verbinden. Registrieren Sie diese Dienste mit dem Abhängigkeitscontainer in der Program.cs Datei Ihrer App, um sie über das Einfügen von Abhängigkeiten verfügbar zu machen.

Führen Sie die folgenden Schritte aus, um die benötigten Dienste zu registrieren:

Fügen Sie das Microsoft.Extensions.Azure-Paket hinzu:
```
dotnet add package Microsoft.Extensions.Azure
```

Fügen Sie die relevanten Azure.* Dienstclientpakete hinzu:

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Messaging.ServiceBus

Rufen Sie in der Program.cs Datei Ihrer App die AddAzureClients Erweiterungsmethode aus der Microsoft.Extensions.Azure Bibliothek auf, um einen Client für die Kommunikation mit jedem Azure-Dienst zu registrieren. Einige Clientbibliotheken bieten zusätzliche Unterclients für bestimmte Untergruppen von Azure-Dienstfunktionen. Sie können solche Unterclients für die Abhängigkeitseinfügung über die AddClient Erweiterungsmethode registrieren.

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Einfügen der registrierten Clients in Ihre ASP.NET Core-App-Komponenten, -Dienste oder -API-Endpunkt:

Minimale API
Blazor

app.MapGet("/reports", async (
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory) =>
{
    // Create the named client
    ServiceBusSender serviceBusSender = senderFactory.CreateClient("queue1");

    await serviceBusSender.SendMessageAsync(new ServiceBusMessage("Hello world"));

    // Use the blob client
    BlobContainerClient containerClient
        = blobServiceClient.GetBlobContainerClient("reports");

    List<BlobItem> reports = new();
    await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
    {
        reports.Add(blobItem);
    }

    return reports;
})
.WithName("GetReports");

@page "/"
@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models
@using Azure.Messaging.ServiceBus
@using Microsoft.Extensions.Azure;

<h1>Reports</h1>

<ul>
    @foreach (var report in reports)
    {
        <li>@report.Name</li>
    }
</ul>

@code {
    List<BlobItem> reports = new();

    private BlobServiceClient _blobServiceClient;
    private ServiceBusSender _serviceBusSender;

    public Home(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
         _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("queue1");
    }

Weitere Informationen finden Sie unter Dependency Injection mit dem Azure SDK für .NET.

Authentifizieren mithilfe von Microsoft Entra ID

Tokenbasierte Authentifizierung mit Microsoft Entra ID ist der empfohlene Ansatz zur Authentifizierung von Anforderungen an Azure-Dienste. Um diese Anforderungen zu autorisieren, verwaltet Azure rollenbasierte Zugriffssteuerung (RBAC) den Zugriff auf Azure-Ressourcen basierend auf der Microsoft Entra-Identität eines Benutzers und zugewiesenen Rollen.

Verwenden Sie die Azure Identity-Bibliothek für die oben genannte tokenbasierte Authentifizierungsunterstützung. Die Bibliothek stellt Klassen bereit, z DefaultAzureCredential . B. zum Vereinfachen der Konfiguration sicherer Verbindungen. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren. Weitere Informationen zu diesen Themen finden Sie im Abschnitt "Authentifizierung " des Azure SDK für .NET-Dokumente.

Hinweis

Viele Azure-Dienste ermöglichen ihnen auch die Autorisierung von Anforderungen mithilfe von Schlüsseln. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass die Zugriffsschlüssel niemals an einem unsicheren Ort offengelegt werden. Jeder Benutzer, der über den Zugriffsschlüssel verfügt, kann Anforderungen für die zugeordnete Azure-Ressource autorisieren.

Fügen Sie das Azure.Identity-Paket hinzu:
```
dotnet add package Azure.Identity
```

Rufen Sie in der Program.cs Datei Ihrer App die UseCredential Erweiterungsmethode aus der Microsoft.Extensions.Azure Bibliothek auf, um eine freigegebene DefaultAzureCredential Instanz für alle registrierten Azure-Dienstclients festzulegen:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register a client for each Azure service using inline configuration
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Register a subclient for each Azure Service Bus Queue
    var queueNames = new string[] { "queue1", "queue2" };
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    // Register a shared credential for Microsoft Entra ID authentication
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

DefaultAzureCredential ermittelt verfügbare Anmeldeinformationen in der aktuellen Umgebung und verwendet sie zum Authentifizieren bei Azure-Diensten. Die Reihenfolge und die Speicherorte, in denen DefaultAzureCredential nach Anmeldeinformationen gesucht wird, finden Sie unter DefaultAzureCredential (Übersicht). Durch die Verwendung einer freigegebenen DefaultAzureCredential Instanz wird sichergestellt, dass der zugrunde liegende Tokencache verwendet wird, wodurch die Anwendungsresilienz und -leistung verbessert wird, da weniger Anforderungen für ein neues Token erforderlich sind.

Anwenden von Konfigurationen

Azure SDK-Dienstclients unterstützen Konfigurationen, um ihr Standardverhalten zu ändern. Es gibt zwei Möglichkeiten zum Konfigurieren von Dienstclients:

JSON-Konfigurationsdateien sind im Allgemeinen der empfohlene Ansatz, da sie die Verwaltung von Unterschieden in App-Bereitstellungen zwischen Umgebungen vereinfachen.
Inlinecodekonfigurationen können angewendet werden, wenn Sie den Dienstclient registrieren. Beispielsweise haben Sie im Abschnitt "Clients und Unterclients registrieren" die URI-Variablen explizit an die Clientkonstruktoren übergeben.

IConfiguration Rangfolgeregeln werden von den Microsoft.Extensions.Azure Erweiterungsmethoden beachtet, die in der Dokumentation zu Konfigurationsanbietern ausführlich beschrieben sind.

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre App so zu aktualisieren, dass sie die JSON-Dateikonfiguration für die entsprechenden Umgebungen verwendet. Verwenden Sie die appsettings.Development.json Datei für Entwicklungseinstellungen und die appsettings.Production.json Datei für Produktionsumgebungseinstellungen. Sie können Der JSON-Datei Konfigurationseinstellungen hinzufügen, deren Namen öffentliche Eigenschaften für die ClientOptions Klasse sind.

Konfigurieren registrierter Dienste

Aktualisieren Sie die appsettings.<environment>.json Datei in Ihrer App mit den hervorgehobenen Dienstkonfigurationen:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}
```
Im vorherigen JSON-Beispiel:
- Die Schlüsselnamen der obersten Ebene, KeyVault, ServiceBusund Storage, sind beliebige Namen, die verwendet werden, um auf die Konfigurationsabschnitte aus Ihrem Code zu verweisen. Sie übergeben diese Namen an AddClient Erweiterungsmethoden, um einen bestimmten Client zu konfigurieren. Alle anderen Schlüsselnamen werden bestimmten Clientoptionen zugeordnet, und die JSON-Serialisierung wird ohne Groß-/Kleinschreibung ausgeführt.
- Die KeyVault:VaultUriWerte ServiceBus:Namespaceund Storage:ServiceUri Schlüsselwerte entsprechen den Argumenten der ServiceBusClient(String)SecretClient(Uri, TokenCredential, SecretClientOptions)Überladungen , bzwBlobServiceClient(Uri, TokenCredential, BlobClientOptions). der Konstruktorüberladungen. Die TokenCredential-Varianten der Konstruktoren werden verwendet, da ein Standardwert TokenCredential über den Methodenaufruf UseCredential(TokenCredential) festgelegt wird.

Aktualisieren Sie die Program.cs Datei, um die JSON-Dateikonfigurationen abzurufen, und IConfiguration übergeben Sie sie an Ihre Dienstregistrierungen:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

Konfigurieren von Azure-Standardeinstellungen und Wiederholungen

Sie können die standardmäßigen Azure-Clientkonfigurationen global oder für einen bestimmten Dienstclient ändern. Sie möchten z. B. andere Wiederholungseinstellungen oder eine andere Version der Service-API verwenden. Sie können die Wiederholungseinstellungen global oder dienstspezifisch festlegen.

Aktualisieren Sie Ihre Konfigurationsdatei, um die Standardeinstellungen von Azure festzulegen, z. B. eine neue Standard-Wiederholungsrichtlinie, die alle registrierten Azure-Clients verwenden:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Rufen Sie in der Program.cs Datei die ConfigureDefaults Erweiterungsmethode auf, um die Standardeinstellungen abzurufen und sie auf Ihre Dienstclients anzuwenden:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Register clients using a config file section
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    // Register clients using a specific config key-value pair
    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    // Register a subclient for each Azure Service Bus Queue
    string[] queueNames = [ "queue1", "queue2" ];
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                    .CreateSender(queue)).WithName(queue);
    }

    clientBuilder.UseCredential(new DefaultAzureCredential());

    // Set up any default settings
    clientBuilder.ConfigureDefaults(
        builder.Configuration.GetSection("AzureDefaults"));
});

Konfigurieren der Protokollierung

Das Azure SDK für .NET-Clientbibliotheken kann Clientbibliotheksvorgänge protokollieren, um Anforderungen und Antworten auf Azure-Dienste zu überwachen. Clientbibliotheken können auch eine Vielzahl anderer Ereignisse protokollieren, darunter Wiederholungen, Tokenabrufe und dienstspezifische Ereignisse von verschiedenen Clients. Wenn Sie einen Azure SDK-Client mithilfe der AddAzureClients Erweiterungsmethode registrieren, wird er AzureEventSourceLogForwarder beim Abhängigkeitseinfügungscontainer registriert. Die AzureEventSourceLogForwarder Protokollmeldungen aus Azure SDK-Ereignisquellen werden weitergeleitet, damit ILoggerFactory Sie die Standardkonfiguration ASP.NET Core-Protokollierung für die Protokollierung verwenden können.

Die folgende Tabelle zeigt, wie EventLevel (Azure SDK für .NET) LogLevel (ASP.NET Core) zugeordnet wird. Weitere Informationen zu diesen Themen und anderen Szenarien finden Sie unter Logging with the Azure SDK for .NET and Dependency injection with the Azure SDK for .NET.

Azure SDK `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Sie können Standardprotokollebenen und andere Einstellungen mithilfe der gleichen JSON-Konfigurationen ändern, die im Abschnitt "Authentifizierung konfigurieren" beschrieben sind. Schalten Sie z. B. die ServiceBusClient Protokollebene wie folgt ein Debug , indem Sie den Logging:LogLevel:Azure.Messaging.ServiceBus Schlüssel wie folgt festlegen:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Messaging.ServiceBus": "Debug"
    }
  },
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://<your-key-vault-name>.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
  }
}

Freigeben über