Korzystanie z zestawu Azure SDK dla platformy .NET w aplikacjach platformy ASP.NET Core

Artykuł
03/05/2025

Zestaw Azure SDK dla platformy .NET umożliwia integrację aplikacji ASP.NET Core z wieloma różnymi usługami platformy Azure. W tym artykule poznasz najlepsze rozwiązania i kroki wdrażania zestawu Azure SDK dla platformy .NET w aplikacjach platformy ASP.NET Core. Dowiesz się, jak:

Rejestrowanie usług do wstrzykiwania zależności.
Uwierzytelnianie na platformie Azure bez używania haseł lub wpisów tajnych.
Zaimplementuj scentralizowaną, ustandaryzowaną konfigurację.
Skonfiguruj typowe problemy dotyczące aplikacji internetowej, takie jak rejestrowanie i ponawianie prób.

Eksplorowanie typowych bibliotek klienckich zestawu Azure SDK

ASP.NET Core aplikacje, które łączą się z usługami platformy Azure, zwykle zależą od następujących bibliotek klienckich zestawu Azure SDK:

Microsoft.Extensions.Azure udostępnia metody pomocnicze do rejestrowania klientów w kolekcji usług wstrzykiwania zależności i obsługuje różne aspekty, takie jak konfigurowanie rejestrowania, obsługa czasów życia usług DI i zarządzanie poświadczeniami uwierzytelniania.
Usługa Azure.Identity umożliwia obsługę uwierzytelniania identyfikatora Entra firmy Microsoft w zestawie Azure SDK. Udostępnia zestaw implementacji TokenCredential do konstruowania klientów zestawu Azure SDK, którzy obsługują uwierzytelnianie firmy Microsoft Entra.
Azure.<service-namespace> biblioteki, takie jak Azure.Storage.Blobs i Azure.Messaging.ServiceBus, udostępniają klientów usług i inne typy, aby ułatwić nawiązywanie połączenia z określonymi usługami platformy Azure i korzystanie z nich. Aby uzyskać pełny spis tych bibliotek, zobacz Biblioteki korzystające z platformy Azure.Core.

W poniższych sekcjach dowiesz się, jak zaimplementować aplikację platformy ASP.NET Core korzystającą z tych bibliotek.

Rejestrowanie klientów zestawu Azure SDK przy użyciu kolekcji usług DI

Biblioteki klienckie zestawu Azure SDK dla platformy .NET zapewniają klientom usług łączenie aplikacji z usługami platformy Azure, takimi jak Azure Blob Storage i Azure Key Vault. Zarejestruj te usługi w kontenerze zależności w Program.cs pliku aplikacji, aby udostępnić je za pośrednictwem wstrzykiwania zależności.

Wykonaj następujące kroki, aby zarejestrować potrzebne usługi:

Dodaj pakiet Microsoft.Extensions.Azure:

dotnet add package Microsoft.Extensions.Azure

Dodaj odpowiednie Azure.* pakiety klienta usługi:

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

W pliku Program.cs w swojej aplikacji użyj metody rozszerzenia AddAzureClients z biblioteki Microsoft.Extensions.Azure, aby zarejestrować klienta do komunikacji z każdą usługą Azure. Niektóre biblioteki klienckie udostępniają dodatkowe podkliencie dla określonych podgrup funkcji usługi platformy Azure. Możesz zarejestrować takich podklientów na potrzeby wstrzykiwania zależności za pomocą metody rozszerzenia AddClient.

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());
});

Wstrzyknij zarejestrowanych klientów do składników aplikacji, usług lub punktów końcowego interfejsu API w ASP.NET Core.

Minimal 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");
    }

Aby uzyskać więcej informacji, zobacz Wstrzykiwanie zależności za pomocą zestawu Azure SDK dla platformy .NET.

Uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft

Uwierzytelnianie oparte na tokenach przy użyciu identyfikatora Entra firmy Microsoft to zalecane podejście do uwierzytelniania żądań w usługach platformy Azure. Aby autoryzować te żądania, kontrola dostępu oparta na rolach (RBAC) platformy Azure zarządza dostępem do zasobów platformy Azure na podstawie tożsamości microsoft Entra użytkownika i przypisanych ról.

Skorzystaj z biblioteki tożsamości platformy Azure, aby uzyskać obsługę uwierzytelniania opartego na tokenach. Biblioteka udostępnia klasy, takie jak DefaultAzureCredential, aby upraszczać konfigurowanie bezpiecznych połączeń. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska. Aby uzyskać więcej informacji na temat tych tematów, odwiedź sekcję Uwierzytelnianie zestawu Azure SDK dla platformy .NET.

Uwaga

Wiele usług platformy Azure umożliwia również autoryzowanie żądań przy użyciu kluczy. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać klucza dostępu w niezabezpieczonej lokalizacji. Każdy, kto ma klucz dostępu, może autoryzować żądania względem skojarzonego zasobu platformy Azure.

Dodaj pakiet Azure.Identity:
```
dotnet add package Azure.Identity
```

W pliku Program.cs Twojej aplikacji wywołaj metodę rozszerzenia UseCredential z biblioteki Microsoft.Extensions.Azure, aby ustawić udostępnione wystąpienie DefaultAzureCredential dla wszystkich zarejestrowanych klientów usługi platformy Azure.

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 odnajduje dostępne poświadczenia w bieżącym środowisku i używa ich do uwierzytelniania w usługach platformy Azure. Aby zapoznać się z kolejnością i lokalizacjami, w jakich DefaultAzureCredential przeszukuje poświadczenia, zobacz temat Omówienie DefaultAzureCredential. Użycie udostępnionego DefaultAzureCredential wystąpienia zapewnia użycie podstawowej pamięci podręcznej tokenów, co zwiększa odporność i wydajność aplikacji ze względu na mniejszą liczbę żądań o nowy token.

Stosowanie konfiguracji

Klienci usługi Azure SDK obsługują konfiguracje w celu zmiany ich domyślnych zachowań. Istnieją dwa sposoby konfigurowania klientów usługi:

Pliki konfiguracji JSON są zwykle zalecanym podejściem, ponieważ upraszczają zarządzanie różnicami we wdrożeniach aplikacji między środowiskami.
Konfiguracje kodu wbudowanego można stosować podczas rejestrowania klienta usługi. Na przykład w sekcji Rejestrowanie klientów i podklientów jawnie przekazano zmienne URI do konstruktorów klientów.

IConfiguration reguły pierwszeństwa są przestrzegane przez Microsoft.Extensions.Azure metody rozszerzeń, które są szczegółowo opisane w dokumentacji Konfiguracji Dostawców.

Wykonaj kroki opisane w poniższych sekcjach, aby zaktualizować aplikację do używania konfiguracji pliku JSON dla odpowiednich środowisk. Użyj pliku appsettings.Development.json dla ustawień deweloperskich i pliku appsettings.Production.json dla ustawień środowiska produkcyjnego. Do pliku JSON można dodać ustawienia konfiguracji, których nazwy są właściwościami publicznymi w ClientOptions klasie.

Konfigurowanie zarejestrowanych usług

Zaktualizuj plik appsettings.<environment>.json w aplikacji z wyróżnionymi konfiguracjami usługi:
```
{
  "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"
  }
}
```
W poprzednim przykładzie JSON:
- Nazwy kluczy najwyższego poziomu, KeyVault, ServiceBusi Storage, są dowolnymi nazwami używanymi do odwołowania się do sekcji konfiguracji z kodu. Nazwy te przekażesz do metod rozszerzeń AddClient w celu skonfigurowania danego klienta. Wszystkie inne nazwy kluczy są mapowane na określone opcje klienta, a serializacja JSON jest wykonywana w sposób bez uwzględniania wielkości liter.
- Wartości kluczy KeyVault:VaultUri, ServiceBus:Namespace i Storage:ServiceUri są mapowane odpowiednio na argumenty przeciążeń konstruktora SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String) i BlobServiceClient(Uri, TokenCredential, BlobClientOptions). Używane są warianty konstruktorów TokenCredential, ponieważ domyślne TokenCredential jest ustawiane poprzez wywołanie metody UseCredential(TokenCredential).

Zaktualizuj plik Program.cs, aby pobrać konfiguracje plików JSON przy użyciu IConfiguration i przekazać je do rejestracji usług:

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"]);

Konfigurowanie domyślnych ustawień i ustawień ponawiania prób w platformie Azure

Możesz zmienić domyślne konfiguracje klientów platformy Azure globalnie lub dla określonego klienta usługi. Na przykład możesz chcieć użyć różnych ustawień ponawiania prób lub użyć innej wersji interfejsu API usługi. Ustawienia ponawiania można ustawić globalnie lub dla poszczególnych usług.

Zaktualizuj plik konfiguracji, aby ustawić domyślne ustawienia platformy Azure, takie jak nowe domyślne zasady ponawiania, które będą używane przez wszystkich zarejestrowanych klientów platformy Azure:

{
  "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"
  }
}

W pliku Program.cs, wywołaj metodę rozszerzenia ConfigureDefaults, aby pobrać ustawienia domyślne i zastosować je do klientów usługi.

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"));
});

Konfigurowanie rejestrowania

Zestaw Azure SDK dla bibliotek klienckich platformy .NET może rejestrować operacje biblioteki klienta w celu monitorowania żądań i odpowiedzi na usługi platformy Azure. Biblioteki klienckie mogą również rejestrować różne inne zdarzenia, w tym ponawianie prób, pobieranie tokenów i zdarzenia specyficzne dla usługi od różnych klientów. Podczas rejestrowania klienta zestawu Azure SDK przy użyciu metody rozszerzenia AddAzureClients, AzureEventSourceLogForwarder jest rejestrowane w kontenerze iniekcji zależności. AzureEventSourceLogForwarder przekazuje komunikaty dziennika ze źródeł zdarzeń zestawu Azure SDK do ILoggerFactory, umożliwiając korzystanie ze standardowej konfiguracji rejestrowania ASP.NET Core dla logowania.

W poniższej tabeli przedstawiono sposób mapowania zestawu Azure SDK dla platformy .NET EventLevel na platformę ASP.NET Core LogLevel. Aby uzyskać więcej informacji na temat tych tematów i innych scenariuszy, zobacz Rejestrowanie za pomocą zestawu Azure SDK dla platformy .NET i wstrzykiwanie zależności za pomocą zestawu Azure SDK dla platformy .NET.

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

Domyślne poziomy dziennika i inne ustawienia można zmienić przy użyciu tych samych konfiguracji JSON opisanych w sekcji Konfigurowanie uwierzytelniania . Na przykład, przełącz poziom dziennika na Debug, ustawiając klucz Logging:LogLevel:Azure.Messaging.ServiceBus w następujący sposób:

{
  "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"
  }
}

Udostępnij za pośrednictwem