De Azure SDK voor .NET gebruiken in ASP.NET Core-apps

Artikel
03/05/2025

Met de Azure SDK voor .NET kunnen ASP.NET Core-apps worden geïntegreerd met veel verschillende Azure-services. In dit artikel leert u de aanbevolen procedures en de stappen voor de overstap naar de Azure SDK voor .NET in uw ASP.NET Core-apps. U leert het volgende:

Registreer diensten voor afhankelijkheidsinjectie.
Verifiëren bij Azure zonder wachtwoorden of geheimen te gebruiken.
Gecentraliseerde, gestandaardiseerde configuratie implementeren.
Veelvoorkomende aandachtspunten voor web-apps configureren, zoals logregistratie en herhalingen.

Algemene Azure SDK-clientbibliotheken verkennen

ASP.NET Core-apps die verbinding maken met Azure-services, zijn doorgaans afhankelijk van de volgende Azure SDK-clientbibliotheken:

Microsoft.Extensions.Azure biedt helpermethoden voor het registreren van clients bij de dependency injection-service en het afhandelen van verschillende taken voor u, zoals het instellen van logging, het afhandelen van de levensduur van DI-services en het beheer van authenticatiegegevens.
Azure.Identity biedt ondersteuning voor Microsoft Entra ID-verificatie in de Azure SDK. Het biedt een set TokenCredential-implementaties voor het bouwen van Azure SDK-clients die ondersteuning bieden voor Microsoft Entra-verificatie.
Azure.<service-namespace> bibliotheken, zoals Azure.Storage.Blobs en Azure.Messaging.ServiceBus, bieden serviceclients en andere typen waarmee u verbinding kunt maken met specifieke Azure-services en deze kunt gebruiken. Zie Bibliotheken met behulp van Azure.Core voor een volledige inventarisatie van deze bibliotheken.

In de volgende secties leert u hoe u een ASP.NET Core-toepassing implementeert die gebruikmaakt van deze bibliotheken.

Azure SDK-clients registreren bij de DI-serviceverzameling

De Azure SDK voor .NET-clientbibliotheken bieden serviceclients om uw app te verbinden met Azure-services, zoals Azure Blob Storage en Azure Key Vault. Registreer deze services bij de afhankelijkheidscontainer in het Program.cs bestand van uw app om ze beschikbaar te maken via afhankelijkheidsinjectie.

Voer de volgende stappen uit om de services te registreren die u nodig hebt:

Voeg het pakket Microsoft.Extensions.Azure toe:

dotnet add package Microsoft.Extensions.Azure

Voeg de relevante Azure.* serviceclientpakketten toe:

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

Roep in het Program.cs bestand van uw app de AddAzureClients extensiemethode vanuit de Microsoft.Extensions.Azure bibliotheek aan om een client te registreren om te communiceren met elke Azure-service. Sommige clientbibliotheken bieden extra subclients voor specifieke subgroepen van de Azure-servicefunctionaliteit. U kunt dergelijke subclients registreren voor afhankelijkheidsinjectie via de AddClient extensiemethode.

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

Injecteer de geregistreerde clients in uw ASP.NET Core-app-onderdelen, -services of API-eindpunt:

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

Zie Afhankelijkheidsinjectie met de Azure SDK voor .NET voor meer informatie.

Verifiëren met behulp van Microsoft Entra-id

Verificatie op basis van tokens met Microsoft Entra-id is de aanbevolen benadering voor het verifiëren van aanvragen voor Azure-services. Om deze aanvragen te autoriseren, beheert op rollen gebaseerd toegangsbeheer (RBAC) van Azure de toegang tot Azure-resources op basis van de Microsoft Entra-identiteit en toegewezen rollen van een gebruiker.

Gebruik de Azure Identity-bibliotheek voor de bovengenoemde verificatieondersteuning op basis van tokens. De bibliotheek biedt klassen zoals DefaultAzureCredential om het configureren van beveiligde verbindingen te vereenvoudigen. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren. Ga naar de sectie Verificatie van de Azure SDK voor .NET-documenten voor meer informatie over deze onderwerpen.

Notitie

Met veel Azure-services kunt u aanvragen ook autoriseren met behulp van sleutels. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om de toegangssleutel nooit beschikbaar te maken op een onbeveiligde locatie. Iedereen met de toegangssleutel kan aanvragen autoriseren voor de bijbehorende Azure-resource.

Voeg het Azure.Identity-pakket toe:
```
dotnet add package Azure.Identity
```

Roep in het Program.cs bestand van uw app de UseCredential extensiemethode vanuit de Microsoft.Extensions.Azure bibliotheek aan om een gedeeld exemplaar DefaultAzureCredential in te stellen voor alle geregistreerde Azure-serviceclients:

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 detecteert beschikbare referenties in de huidige omgeving en gebruikt deze om te verifiëren bij Azure-services. Zie het overzicht defaultAzureCredential voor de volgorde en locaties waarin DefaultAzureCredential wordt gescand op referenties. Het gebruik van een gedeeld exemplaar DefaultAzureCredential zorgt ervoor dat de onderliggende tokencache wordt gebruikt, waardoor de tolerantie en prestaties van toepassingen worden verbeterd vanwege minder aanvragen voor een nieuw token.

Configuraties toepassen

Azure SDK-serviceclients ondersteunen configuraties om hun standaardgedrag te wijzigen. Er zijn twee manieren om serviceclients te configureren:

JSON-configuratiebestanden zijn over het algemeen de aanbevolen aanpak omdat ze het beheren van verschillen in app-implementaties tussen omgevingen vereenvoudigen.
Inline-codeconfiguraties kunnen worden toegepast wanneer u de serviceclient registreert. In de sectie Clients en subclients registreren hebt u bijvoorbeeld expliciet de URI-variabelen doorgegeven aan de clientconstructors.

IConfiguration prioriteitsregels worden gerespecteerd door de Microsoft.Extensions.Azure uitbreidingsmethoden, die worden beschreven in de documentatie van Configuration Providers .

Voer de stappen in de volgende secties uit om uw app bij te werken voor het gebruik van de JSON-bestandsconfiguratie voor de juiste omgevingen. Gebruik het appsettings.Development.json bestand voor ontwikkelingsinstellingen en het bestand voor de instellingen van de appsettings.Production.json productieomgeving. U kunt configuratie-instellingen toevoegen waarvan de namen openbare eigenschappen van de ClientOptions klasse zijn aan het JSON-bestand.

Geregistreerde services configureren

Werk het appsettings.<environment>.json bestand in uw app bij met de gemarkeerde serviceconfiguraties:
```
{
  "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"
  }
}
```
In het voorgaande JSON-voorbeeld:
- De sleutelnamen op het hoogste niveau, KeyVault, ServiceBusen Storage, zijn willekeurige namen die worden gebruikt om te verwijzen naar de configuratiesecties uit uw code. U geeft deze namen door aan AddClient extensiemethoden om een bepaalde client te configureren. Alle andere sleutelnamen worden toegewezen aan specifieke clientopties en JSON-serialisatie wordt op een niet-hoofdlettergevoelige manier uitgevoerd.
- De KeyVault:VaultUri, ServiceBus:Namespaceen Storage:ServiceUri sleutelwaarden worden respectievelijk toegewezen aan de argumenten van de SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String)en BlobServiceClient(Uri, TokenCredential, BlobClientOptions) constructoroverbelastingen. De TokenCredential varianten van de constructors worden gebruikt omdat een standaardwaarde TokenCredential wordt ingesteld via de UseCredential(TokenCredential) methode-aanroep.

Werk het Program.cs bestand bij om de JSON-bestandsconfiguraties op te halen met behulp van IConfiguration en ze door te geven aan uw serviceregistraties.

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

Azure-standaardinstellingen en herhalingen configureren

Mogelijk wilt u de standaardconfiguraties van Azure-clients globaal of voor een specifieke serviceclient wijzigen. U wilt bijvoorbeeld misschien andere instellingen voor opnieuw proberen instellen of een andere versie van de service-API gebruiken. U kunt de instellingen voor opnieuw proberen globaal of per service instellen.

Werk uw configuratiebestand bij om standaardinstellingen voor Azure in te stellen, zoals een nieuw standaardbeleid voor opnieuw proberen dat door alle geregistreerde Azure-clients wordt gebruikt:

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

Roep in het Program.cs bestand de ConfigureDefaults extensiemethode aan om de standaardinstellingen op te halen en toe te passen op uw serviceclients:

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

Logboekregistratie configureren

De Azure SDK voor .NET-clientbibliotheken kunnen clientbibliotheekbewerkingen vastleggen om aanvragen en antwoorden op Azure-services te bewaken. Clientbibliotheken kunnen ook verschillende andere gebeurtenissen registreren, waaronder nieuwe pogingen, het ophalen van tokens en servicespecifieke gebeurtenissen van verschillende clients. Wanneer u een Azure SDK-client registreert met behulp van de AddAzureClients extensiemethode, wordt de AzureEventSourceLogForwarder client geregistreerd bij de container voor afhankelijkheidsinjectie. De AzureEventSourceLogForwarder stuurt logboekberichten van Azure SDK-evenementbronnen door naar ILoggerFactory, zodat u de standaardconfiguratie voor ASP.NET Core-logboekregistratie kunt gebruiken.

In de volgende tabel ziet u hoe de Azure SDK voor .NET EventLevel wordt toegewezen aan de ASP.NET Core LogLevel. Zie voor meer informatie over deze onderwerpen en andere scenario's Logboekregistratie met de Azure SDK voor .NET en Afhankelijkheidsinjectie met de Azure SDK voor .NET.

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

U kunt standaardlogboekniveaus en andere instellingen wijzigen met dezelfde JSON-configuraties die worden beschreven in de sectie Verificatie configureren. Schakel bijvoorbeeld het ServiceBusClient logboekniveau Debug in door de Logging:LogLevel:Azure.Messaging.ServiceBus sleutel als volgt in te stellen:

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

Delen via