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

Artykuł
11/16/2024

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 na potrzeby 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 pomocnika do rejestrowania klientów w kolekcji usług wstrzykiwania zależności i obsługuje różne problemy, takie jak konfigurowanie rejestrowania, obsługa okresów istnienia usługi 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 aplikacji wywołaj Program.cs AddAzureClients metodę rozszerzenia z Microsoft.Extensions.Azure biblioteki, aby zarejestrować klienta w celu komunikowania się z każdą usługą platformy Azure. Niektóre biblioteki klienckie udostępniają dodatkowe podkliencie dla określonych podgrup funkcji usługi platformy Azure. Takie podklienci można zarejestrować na potrzeby wstrzykiwania zależności za pomocą AddClient metody rozszerzenia.

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

Wstrzyknąć zarejestrowanych klientów do składników, usług lub punktu końcowego interfejsu API ASP.NET Core:

Minimalny interfejs 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 upraszczanie konfigurowania 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 aplikacji wywołaj Program.cs UseCredential metodę rozszerzenia z Microsoft.Extensions.Azure biblioteki, aby ustawić wystąpienie udostępnione 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 których DefaultAzureCredential skanowanie pod kątem poświadczeń znajduje się w temacie DefaultAzureCredential overview (Omówienie domyślnego obiektu AzureCredential). Użycie udostępnionego DefaultAzureCredential wystąpienia zapewnia użycie podstawowej pamięci podręcznej tokenów, co zwiększa odporność i wydajność aplikacji z powodu mniejszej liczby żądań dla nowego tokenu.

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 podklienci jawnie przekazano zmienne identyfikatora URI do konstruktorów klienta.

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

Wykonaj kroki opisane w poniższych sekcjach, aby zaktualizować aplikację do używania konfiguracji pliku JSON dla odpowiednich środowisk. appsettings.Development.json Użyj pliku dla ustawień programowania i appsettings.Production.json pliku 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

appsettings.<environment>.json Zaktualizuj plik w aplikacji za pomocą wyróżnionych konfiguracji 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. Te nazwy zostaną przekazane do AddClient metod rozszerzeń w celu skonfigurowania danego klienta. Wszystkie inne nazwy kluczy są mapować na określone opcje klienta, a serializacja JSON jest wykonywana w sposób bez uwzględniania wielkości liter.
- KeyVault:VaultUriWartości , ServiceBus:Namespacei , i Storage:ServiceUri są mapowanie odpowiednio na argumenty SecretClient(Uri, TokenCredential, SecretClientOptions)ServiceBusClient(String)przeciążeń , i BlobServiceClient(Uri, TokenCredential, BlobClientOptions) konstruktora. Używane TokenCredential są warianty konstruktorów, ponieważ ustawienie domyślne TokenCredential jest ustawiane za pośrednictwem wywołania UseCredential(TokenCredential) metody.

Zaktualizuj plik, Program.cs aby pobrać konfiguracje plików JSON przy użyciu polecenia IConfiguration i przekazać je do rejestracji 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"]);

Konfigurowanie domyślnych i ponownych prób platformy 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 wywołaj Program.cs metodę ConfigureDefaults rozszerzenia, 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 AddAzureClients metody AzureEventSourceLogForwarder rozszerzenia parametr jest rejestrowany w kontenerze iniekcji zależności. Przesyła AzureEventSourceLogForwarder dalej komunikaty dziennika ze źródeł zdarzeń zestawu Azure SDK, aby ILoggerFactory umożliwić korzystanie ze standardowej konfiguracji rejestrowania ASP.NET Core na potrzeby rejestrowania.

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 ServiceBusClient Debug , ustawiając klucz w Logging:LogLevel:Azure.Messaging.ServiceBus 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