Sdílet prostřednictvím

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

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é aspekty webových aplikací, jako je protokolování a opakované pokusy.

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

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

  • Microsoft.Extensions.Azure poskytuje pomocné metody pro registraci klientů v systému injektování závislostí a řeší různé aspekty, jako je nastavení protokolování, zpracování životnosti služeb DI a správa autentizačních přihlašovacích údajů.
  • Azure.Identity umožňuje podporu ověřování Microsoft Entra ID napříč sadou Azure SDK. Poskytuje sadu TokenCredential implementací 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 pomohou připojit se ke konkrétním službám Azure a tyto využívat. 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:

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

    dotnet add package Microsoft.Extensions.Azure

  2. 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

  3. 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 vkládání 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);
    }
});

var app = builder.Build();

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

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

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, které zjednodušují konfiguraci 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 opatrní, aby nikdy nezpřístupnili přístupový klíč v nezabezpečeném místě. Každý, kdo má přístupový klíč, může autorizovat požadavky na přidružený prostředek Azure.

  1. Přidejte balíček Azure.Identity:

    dotnet add package Azure.Identity

  2. Program.cs V souboru vaší aplikace vyvolejte metodu AddAzureClients 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);
    }
});

var app = builder.Build();

    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. Najdete pořadí a umístění, v jakých DefaultAzureCredential hledá přihlašovací údaje, 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 inline kódu můžete 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

  1. 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 klíčů KeyVault:VaultUri, ServiceBus:Namespace a Storage:ServiceUri odpovídají argumentům přetížení konstruktoru SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String) a BlobServiceClient(Uri, TokenCredential, BlobClientOptions) v uvedeném pořadí.

  2. Aktualizujte soubor Program.cs, abyste načetli konfigurace souborů JSON pomocí IConfiguration a předali 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 opakujících pokusů

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.

  1. 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"
  }
}

  2. V souboru Program.cs zavolejte metodu rozšíření ConfigureDefaults, která načte výchozí nastavení a použijte je pro vaše klienty služby.

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

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

var app = builder.Build();

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 Azure SDK pomocí AddAzureClients metody rozšíření, AzureEventSourceLogForwarder je zaregistrován v kontejneru pro injektování závislostí. Přesměrování AzureEventSourceLogForwarder zpráv protokolu z událostí ze zdrojů Azure SDK do ILoggerFactory vám 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 přiřazuje k 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í . Například můžete změnit úroveň protokolu ServiceBusClient na Debug tak, že nastavíte klíč Logging:LogLevel:Azure.Messaging.ServiceBus následujícím způsobem:

{
  "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"
  }
}
  • Last updated on