Použití sady Azure SDK pro .NET v aplikacích ASP.NET Core

Článek
11/16/2024

Sada Azure SDK pro .NET umožňuje integraci aplikací ASP.NET Core s mnoha různými službami Azure. V tomto článku se seznámíte s osvědčenými postupy a kroky k přijetí sady Azure SDK pro .NET ve vašich aplikacích ASP.NET Core. Získáte následující informace:

Zaregistrujte služby pro injektáž závislostí.
Ověřování v Azure bez použití hesel nebo tajných kódů
Implementujte centralizovanou standardizovanou konfiguraci.
Nakonfigurujte běžné obavy z webových aplikací, jako je protokolování a opakování.

Prozkoumání běžných klientských knihoven sady Azure SDK

ASP.NET základní aplikace, které se připojují ke službám Azure, obecně závisí na následujících klientských knihovnách Sady Azure SDK:

Microsoft.Extensions.Azure poskytuje pomocné metody pro registraci klientů v kolekci služeb injektáž závislostí a zpracovává různé obavy, jako je nastavení protokolování, zpracování životností služby DI a správa přihlašovacích údajů ověřování.
Azure.Identity umožňuje podporu ověřování Microsoft Entra ID napříč sadou Azure SDK. Poskytuje sadu implementací TokenCredential pro vytváření klientů Azure SDK, kteří podporují ověřování Microsoft Entra.
Azure.<service-namespace> knihovny, jako jsou Azure.Storage.Blobs a Azure.Messaging.ServiceBus, poskytují klienty služeb a další typy, které vám pomůžou připojit se ke konkrétním službám Azure a využívat je. Kompletní inventář těchto knihoven najdete v tématu Knihovny využívající Azure.Core.

V dalších částech se dozvíte, jak implementovat aplikaci ASP.NET Core, která tyto knihovny používá.

Registrace klientů Azure SDK v kolekci služeb DI

Klientské knihovny Azure SDK pro .NET poskytují klientům služby pro připojení aplikace ke službám Azure, jako je Azure Blob Storage a Azure Key Vault. Zaregistrujte tyto služby pomocí kontejneru závislostí v Program.cs souboru vaší aplikace, abyste je mohli zpřístupnit prostřednictvím injektáže závislostí.

Pokud chcete zaregistrovat služby, které potřebujete, proveďte následující kroky:

Přidejte balíček Microsoft.Extensions.Azure:

dotnet add package Microsoft.Extensions.Azure

Přidejte příslušné Azure.* balíčky klienta služby:

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

Program.cs V souboru vaší aplikace vyvolejte metodu AddAzureClients rozšíření z Microsoft.Extensions.Azure knihovny a zaregistrujte klienta pro komunikaci s každou službou Azure. Některé klientské knihovny poskytují další dílčí klienty pro konkrétní podskupiny funkcí služby Azure. Tyto dílčí klienty můžete zaregistrovat pro injektáž závislostí prostřednictvím AddClient metody rozšíření.

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

Vložte zaregistrované klienty do komponent aplikace ASP.NET Core, služeb nebo koncového bodu rozhraní API:

Minimální rozhraní 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");
    }

Další informace najdete v tématu Injektáž závislostí pomocí sady Azure SDK pro .NET.

Ověřování pomocí ID Microsoft Entra

Ověřování na základě tokenů pomocí Microsoft Entra ID je doporučeným přístupem k ověřování požadavků na služby Azure. K autorizaci těchto požadavků spravuje řízení přístupu na základě role (RBAC) Azure přístup k prostředkům Azure na základě identity Microsoft Entra a přiřazených rolí uživatele.

Pro podporu ověřování na základě výše uvedených tokenů použijte knihovnu Identit Azure. Knihovna poskytuje třídy, jako DefaultAzureCredential je zjednodušení konfigurace zabezpečených připojení. DefaultAzureCredential podporuje více metod ověřování a určuje, která metoda se má použít za běhu. Tento přístup umožňuje vaší aplikaci používat různé metody ověřování v různých prostředích (místní a produkční) bez implementace kódu specifického pro prostředí. Další podrobnosti o těchto tématech najdete v části Ověřování v dokumentaci k sadě Azure SDK pro .NET.

Poznámka:

Mnoho služeb Azure také umožňuje autorizovat žádosti pomocí klíčů. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby nikdy nezpřístupnil přístupový klíč v nezabezpečeném umístění. Každý, kdo má přístupový klíč, může autorizovat požadavky na přidružený prostředek Azure.

Přidejte balíček Azure.Identity:
```
dotnet add package Azure.Identity
```

Program.cs V souboru vaší aplikace vyvolejte metodu UseCredential rozšíření z Microsoft.Extensions.Azure knihovny a nastavte sdílenou DefaultAzureCredential instanci pro všechny registrované klienty služby 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 zjistí dostupné přihlašovací údaje v aktuálním prostředí a používá je k ověření ve službách Azure. Pořadí a umístění, ve kterých DefaultAzureCredential se hledají přihlašovací údaje, najdete v přehledu DefaultAzureCredential. Použití sdílené DefaultAzureCredential instance zajišťuje použití základní mezipaměti tokenů, což zlepšuje odolnost aplikace a výkon kvůli menšímu počtu požadavků na nový token.

Použití konfigurací

Klienti služby Azure SDK podporují konfigurace pro změnu výchozího chování. Klienty služeb můžete nakonfigurovat dvěma způsoby:

Konfigurační soubory JSON jsou obecně doporučeným přístupem, protože zjednodušují správu rozdílů v nasazeních aplikací mezi prostředími.
Konfigurace vloženého kódu je možné použít při registraci klienta služby. Například v části Registrovat klienty a podřízené klienty explicitně předáte proměnné identifikátoru URI konstruktorům klienta.

IConfiguration pravidla priority jsou dodržena metodami Microsoft.Extensions.Azure rozšíření, které jsou podrobně popsány v dokumentaci zprostředkovatelů konfigurace.

Dokončete kroky v následujících částech a aktualizujte aplikaci tak, aby používala konfiguraci souboru JSON pro příslušná prostředí. Použijte soubor appsettings.Development.json pro nastavení vývoje a appsettings.Production.json soubor pro nastavení produkčního prostředí. Do souboru JSON můžete přidat nastavení konfigurace, jejichž názvy jsou veřejné vlastnosti třídy ClientOptions .

Konfigurace registrovaných služeb

appsettings.<environment>.json Aktualizujte soubor v aplikaci se zvýrazněnými konfiguracemi služby:
```
{
  "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"
  }
}
```
V předchozí ukázce JSON:
- Názvy klíčů nejvyšší úrovně , KeyVault, ServiceBusa Storage, jsou libovolné názvy, které slouží k odkaz na konfigurační oddíly z kódu. Tyto názvy AddClient předáte metodám rozšíření pro konfiguraci daného klienta. Všechny ostatní názvy klíčů se mapují na konkrétní možnosti klienta a serializace JSON se provádí bez rozlišování malých a velkých písmen.
- Hodnoty KeyVault:VaultUri, ServiceBus:Namespacea Storage:ServiceUri klíče mapují na argumenty , SecretClient(Uri, TokenCredential, SecretClientOptions)ServiceBusClient(String)a BlobServiceClient(Uri, TokenCredential, BlobClientOptions) konstruktor přetížení, v uvedeném pořadí. Varianty TokenCredential konstruktorů se používají, protože výchozí TokenCredential nastavení je nastaveno prostřednictvím UseCredential(TokenCredential) volání metody.

Program.cs Aktualizujte soubor tak, aby načetl konfigurace souborů JSON pomocí IConfiguration a předal je do registrací služeb:

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

Konfigurace výchozích hodnot Azure a opakování

Možná budete chtít změnit výchozí konfigurace klientů Azure globálně nebo pro konkrétního klienta služby. Můžete například chtít různá nastavení opakování nebo použít jinou verzi rozhraní API služby. Nastavení opakování můžete nastavit globálně nebo podle jednotlivých služeb.

Aktualizujte konfigurační soubor tak, aby nastavil výchozí nastavení Azure, například novou výchozí zásadu opakování, kterou budou používat všichni zaregistrovaní klienti 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"
  }
}

Program.cs V souboru zavolejte metodu ConfigureDefaults rozšíření, která načte výchozí nastavení a použije je u klientů služeb:

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

Konfigurace protokolování

Klientské knihovny Azure SDK pro .NET můžou protokolovat operace klientské knihovny za účelem monitorování požadavků a odpovědí na služby Azure. Klientské knihovny můžou také protokolovat řadu dalších událostí, včetně opakovaných pokusů, načítání tokenů a událostí specifických pro službu z různých klientů. Když zaregistrujete klienta sady Azure SDK pomocí AddAzureClients metody rozšíření, AzureEventSourceLogForwarder zaregistruje se kontejner injektáž závislostí. Předávání AzureEventSourceLogForwarder zpráv protokolu ze zdrojů ILoggerFactory událostí Sady Azure SDK umožňuje používat standardní konfiguraci protokolování ASP.NET Core pro protokolování.

Následující tabulka znázorňuje, jak se sada Azure SDK pro .NET EventLevel mapuje na ASP.NET Core LogLevel. Další informace o těchto tématech a dalších scénářích najdete v tématu Protokolování pomocí sady Azure SDK pro .NET a injektáž závislostí pomocí sady Azure SDK pro .NET.

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

Výchozí úrovně protokolu a další nastavení můžete změnit pomocí stejných konfigurací JSON uvedených v části konfigurace ověřování . Úroveň protokolu můžete například přepnout ServiceBusClient Debug tak, že klíč nastavíte Logging:LogLevel:Azure.Messaging.ServiceBus takto:

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

Sdílet prostřednictvím