Använda Azure SDK för .NET i ASP.NET Core-appar

Artikel
11/16/2024

Med Azure SDK för .NET kan ASP.NET Core-appar integreras med många olika Azure-tjänster. I den här artikeln får du lära dig metodtips och stegen för att implementera Azure SDK för .NET i dina ASP.NET Core-appar. Du lär dig att:

Registrera tjänster för beroendeinmatning.
Autentisera till Azure utan att använda lösenord eller hemligheter.
Implementera centraliserad, standardiserad konfiguration.
Konfigurera vanliga problem med webbappar, till exempel loggning och återförsök.

Utforska vanliga Azure SDK-klientbibliotek

ASP.NET Core-appar som ansluter till Azure-tjänster beror vanligtvis på följande Azure SDK-klientbibliotek:

Microsoft.Extensions.Azure tillhandahåller hjälpmetoder för att registrera klienter med insamlingen av beroendeinmatningstjänsten och hanterar olika problem för dig, till exempel konfiguration av loggning, hantering av DI-tjänstens livslängd och hantering av autentiseringsuppgifter.
Azure.Identity möjliggör Stöd för Microsoft Entra-ID-autentisering i Hela Azure SDK. Den innehåller en uppsättning TokenCredential-implementeringar för att konstruera Azure SDK-klienter som stöder Microsoft Entra-autentisering.
Azure.<service-namespace> bibliotek, till exempel Azure.Storage.Blobs och Azure.Messaging.ServiceBus, tillhandahåller tjänstklienter och andra typer som hjälper dig att ansluta till och använda specifika Azure-tjänster. En fullständig inventering av dessa bibliotek finns i Bibliotek med Azure.Core.

I de kommande avsnitten utforskar du hur du implementerar ett ASP.NET Core-program som använder dessa bibliotek.

Registrera Azure SDK-klienter med DI-tjänstsamlingen

Azure SDK för .NET-klientbibliotek tillhandahåller tjänstklienter för att ansluta din app till Azure-tjänster som Azure Blob Storage och Azure Key Vault. Registrera dessa tjänster med beroendecontainern i Program.cs appens fil för att göra dem tillgängliga via beroendeinmatning.

Utför följande steg för att registrera de tjänster du behöver:

Lägg till Microsoft.Extensions.Azure-paketet:

dotnet add package Microsoft.Extensions.Azure

Lägg till relevanta Azure.* tjänstklientpaket:

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

I filen i Program.cs din app anropar AddAzureClients du tilläggsmetoden från Microsoft.Extensions.Azure biblioteket för att registrera en klient för att kommunicera med varje Azure-tjänst. Vissa klientbibliotek tillhandahåller ytterligare underklienter för specifika undergrupper av Azure-tjänstfunktioner. Du kan registrera sådana underklienter för beroendeinmatning via AddClient tilläggsmetoden.

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

Mata in de registrerade klienterna i dina ASP.NET Core-appkomponenter, tjänster eller API-slutpunkter:

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

Mer information finns i Beroendeinmatning med Azure SDK för .NET.

Autentisera med Microsoft Entra-ID

Tokenbaserad autentisering med Microsoft Entra-ID är den rekommenderade metoden för att autentisera begäranden till Azure-tjänster. För att auktorisera dessa begäranden hanterar rollbaserad åtkomstkontroll (RBAC) åtkomst till Azure-resurser baserat på en användares Microsoft Entra-identitet och tilldelade roller.

Använd Azure Identity-biblioteket för ovan nämnda tokenbaserade autentiseringsstöd. Biblioteket innehåller klasser som till exempel DefaultAzureCredential för att förenkla konfigurationen av säkra anslutningar. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod. Mer information om dessa ämnen finns i avsnittet Autentisering i Azure SDK för .NET-dokument.

Kommentar

Med många Azure-tjänster kan du också auktorisera begäranden med hjälp av nycklar. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera åtkomstnyckeln på en osäker plats. Alla som har åtkomstnyckeln kan auktorisera begäranden mot den associerade Azure-resursen.

Lägg till Azure.Identity-paketet:
```
dotnet add package Azure.Identity
```

I filen i Program.cs din app anropar du tilläggsmetoden från biblioteket för att ange en delad DefaultAzureCredential instans för alla registrerade Azure-tjänstklienter UseCredential Microsoft.Extensions.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 identifierar tillgängliga autentiseringsuppgifter i den aktuella miljön och använder dem för att autentisera till Azure-tjänster. För den ordning och de platser där DefaultAzureCredential genomsökningar efter autentiseringsuppgifter finns i Översikt över StandardAzureCredential. Genom att använda en delad DefaultAzureCredential instans säkerställer du att den underliggande tokencachen används, vilket förbättrar programmets motståndskraft och prestanda på grund av färre begäranden om en ny token.

Tillämpa konfigurationer

Azure SDK-tjänstklienter stöder konfigurationer för att ändra deras standardbeteenden. Det finns två sätt att konfigurera tjänstklienter:

JSON-konfigurationsfiler är vanligtvis den rekommenderade metoden eftersom de förenklar hanteringen av skillnader i appdistributioner mellan miljöer.
Infogade kodkonfigurationer kan användas när du registrerar tjänstklienten. I avsnittet Registrera klienter och underklienter skickade du till exempel uttryckligen URI-variablerna till klientkonstruktorerna.

IConfiguration prioritetsregler respekteras av tilläggsmetoderna Microsoft.Extensions.Azure , som beskrivs i dokumentationen för konfigurationsproviders .

Slutför stegen i följande avsnitt för att uppdatera appen så att den använder JSON-filkonfiguration för lämpliga miljöer. appsettings.Development.json Använd filen för utvecklingsinställningar och appsettings.Production.json filen för inställningar för produktionsmiljön. Du kan lägga till konfigurationsinställningar vars namn är offentliga egenskaper för ClientOptions klassen i JSON-filen.

Konfigurera registrerade tjänster

appsettings.<environment>.json Uppdatera filen i din app med de markerade tjänstkonfigurationerna:
```
{
  "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"
  }
}
```
I föregående JSON-exempel:
- Nyckelnamnen på den översta nivån, KeyVault, ServiceBusoch Storage, är godtyckliga namn som används för att referera till konfigurationsavsnitten från koden. Du skickar dessa namn till AddClient tilläggsmetoder för att konfigurera en viss klient. Alla andra nyckelnamn mappas till specifika klientalternativ och JSON-serialisering utförs på ett skiftlägesokänsligt sätt.
- Nyckelvärdena KeyVault:VaultUri, ServiceBus:Namespaceoch Storage:ServiceUri mappas till argumenten för SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String)och BlobServiceClient(Uri, TokenCredential, BlobClientOptions) konstruktorns överlagringar. Varianterna TokenCredential av konstruktorerna används eftersom ett standardvärde TokenCredential anges via metodanropet UseCredential(TokenCredential) .

Program.cs Uppdatera filen för att hämta JSON-filkonfigurationerna med och IConfiguration skicka dem till dina tjänstregistreringar:

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

Konfigurera Standardinställningar och återförsök i Azure

Du kanske vill ändra standardkonfigurationerna för Azure-klient globalt eller för en specifik tjänstklient. Du kanske till exempel vill ha olika återförsöksinställningar eller använda en annan version av tjänst-API:et. Du kan ange återförsöksinställningarna globalt eller per tjänst.

Uppdatera konfigurationsfilen för att ange standardinställningar för Azure, till exempel en ny standardprincip för återförsök som alla registrerade Azure-klienter använder:

{
  "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 I filen anropar du ConfigureDefaults tilläggsmetoden för att hämta standardinställningarna och tillämpa dem på dina tjänstklienter:

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

Konfigurera loggning

Azure SDK för .NET-klientbibliotek kan logga klientbiblioteksåtgärder för att övervaka begäranden och svar på Azure-tjänster. Klientbibliotek kan också logga en mängd andra händelser, inklusive återförsök, tokenhämtning och tjänstspecifika händelser från olika klienter. När du registrerar en Azure SDK-klient med hjälp av AddAzureClients tilläggsmetoden AzureEventSourceLogForwarder registreras den med containern för beroendeinmatning. Vidarebefordrar AzureEventSourceLogForwarder loggmeddelanden från Azure SDK-händelsekällor till ILoggerFactory så att du kan använda standardkonfigurationen för ASP.NET Core-loggning för loggning.

Följande tabell visar hur Azure SDK för .NET EventLevel mappar till ASP.NET Core LogLevel. Mer information om dessa ämnen och andra scenarier finns i Loggning med Azure SDK för .NET och Beroendeinmatning med Azure SDK för .NET.

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

Du kan ändra standardloggnivåer och andra inställningar med samma JSON-konfigurationer som beskrivs i avsnittet konfigurera autentisering . Du kan till exempel växla ServiceBusClient loggnivån till genom att Debug ange Logging:LogLevel:Azure.Messaging.ServiceBus nyckeln på följande sätt:

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

Dela via