Beroendeinmatning med Azure SDK för .NET

Artikel
10/31/2024

Den här artikeln visar hur du registrerar Azure-tjänstklienter från de senaste Azure-klientbiblioteken för .NET för beroendeinmatning i en .NET-app. Varje modern .NET-app startas med hjälp av anvisningarna i en Program.cs fil.

Installera paket

Så här registrerar och konfigurerar du tjänstklienter från ett Azure.-prefix-paket:

Installera Microsoft.Extensions.Azure-paketet i projektet:
```
dotnet add package Microsoft.Extensions.Azure
```
Installera Azure.Identity-paketet för att konfigurera en TokenCredential typ som ska användas för att autentisera alla registrerade klienter som accepterar en sådan typ:
```
dotnet add package Azure.Identity
```

I demonstrationssyfte använder exempelkoden i den här artikeln Key Vault-biblioteken Hemligheter, Blob Storage, Service Bus och Azure OpenAI. Installera följande paket för att följa med:

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

Registrera klienter och underklienter

En tjänstklient är startpunkten för API:et för en Azure-tjänst – från den kan biblioteksanvändare anropa alla åtgärder som tjänsten tillhandahåller och enkelt implementera de vanligaste scenarierna. Om det förenklar utformningen av ett API kan grupper av tjänstanrop ordnas runt mindre underklienttyper. Du kan till exempel ServiceBusClient registrera ytterligare ServiceBusSender underklienter för att publicera meddelanden eller ServiceBusReceiver underklienter för att använda meddelanden.

I filen Program.cs anropar AddAzureClients du tilläggsmetoden för att registrera en klient för varje tjänst. Följande kodexempel ger vägledning om programbyggare från namnrymderna Microsoft.AspNetCore.Builder och Microsoft.Extensions.Hosting .

using Azure.Identity;
using Azure.Messaging.ServiceBus;
using Azure.Messaging.ServiceBus.Administration;
using Microsoft.Extensions.Azure;
using Azure.AI.OpenAI;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddAzureClients(async clientBuilder =>
{
    // Register clients for each service
    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
    clientBuilder.AddServiceBusClientWithNamespace(
        "<your_namespace>.servicebus.windows.net");

    // Set a credential for all clients to use by default
    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);

    // Register a subclient for each Service Bus Queue
    List<string> queueNames = await GetQueueNames(credential);
    foreach (string queue in queueNames)
    {
        clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>(
            (_, _, provider) => provider.GetService<ServiceBusClient>()
                .CreateSender(queue)).WithName(queue);
    }

    // Register a custom client factory
    clientBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>(
        (options, _, _) => new AzureOpenAIClient(
            new Uri("<url_here>"), credential, options)); 
});

WebApplication app = builder.Build();

async Task<List<string>> GetQueueNames(DefaultAzureCredential credential)
{
    // Query the available queues for the Service Bus namespace.
    var adminClient = new ServiceBusAdministrationClient
        ("<your_namespace>.servicebus.windows.net", credential);
    var queueNames = new List<string>();

    // Because the result is async, the queue names need to be captured
    // to a standard list to avoid async calls when registering. Failure to
    // do so results in an error with the services collection.
    await foreach (QueueProperties queue in adminClient.GetQueuesAsync())
    {
        queueNames.Add(queue.Name);
    }

    return queueNames;
}

using Azure.Identity;
using Azure.Messaging.ServiceBus;
using Azure.Messaging.ServiceBus.Administration;
using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Hosting;
using Azure.AI.OpenAI;

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddAzureClients(async clientBuilder =>
        {
            // Register clients for each service
            clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
            clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
            clientBuilder.AddServiceBusClientWithNamespace("<your_namespace>.servicebus.windows.net");
            
            // Set a credential for all clients to use by default
            DefaultAzureCredential credential = new();
            clientBuilder.UseCredential(credential);

            // Register subclients for Service Bus
            List<string> queueNames = await GetQueueNames(credential);
            foreach (string queueName in queueNames)
            {
                clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>((_, _, provider) =>
                provider.GetService(typeof(ServiceBusClient)) switch
                {
                    ServiceBusClient client => client.CreateSender(queueName),
                    _ => throw new InvalidOperationException("Unable to create ServiceBusClient")
                }).WithName(queueName);
            }

            // Register a custom client factory
            clientBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>(
                (options, _, _) => new AzureOpenAIClient(
                    new Uri("<url_here>"), credential, options)); 
        });
    }).Build();

await host.RunAsync();

async Task<List<string>> GetQueueNames(DefaultAzureCredential credential)
{
    // Query the available queues for the Service Bus namespace.
    var adminClient = new ServiceBusAdministrationClient
        ("<your_namespace>.servicebus.windows.net", credential);
    var queueNames = new List<string>();

    // Because the result is async, the queue names need to be captured
    // to a standard list to avoid async calls when registering. Failure to 
    // do so results in an error with the services collection.
    await foreach (QueueProperties queue in adminClient.GetQueuesAsync())
    {
        queueNames.Add(queue.Name);
    }

    return queueNames;
}

using Azure.Identity;
using Azure.Messaging.ServiceBus;
using Azure.Messaging.ServiceBus.Administration;
using Microsoft.Extensions.Azure;
using Azure.AI.OpenAI;

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddAzureClients(async clientBuilder =>
        {
            // Register clients for each service
            clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
            clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
            clientBuilder.AddServiceBusClientWithNamespace("<your_namespace>.servicebus.windows.net");
            
            // Set a credential for all clients to use by default
            DefaultAzureCredential credential = new();
            clientBuilder.UseCredential(credential);

            // Register a subclient for each Service Bus Queue
            List<string> queueNames = await GetQueueNames(credential);
            foreach (string queue in queueNames)
            {
                clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>((_, _, provider) =>
                    provider.GetService<ServiceBusClient>().CreateSender(queue)
                ).WithName(queue);
            }

            // Register a custom client factory
            clientBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>(
                (options, _, _) => new AzureOpenAIClient(
                    new Uri("<url_here>"), credential, options)); 
        });
    }).Build();

await host.RunAsync();

async Task<List<string>> GetQueueNames(DefaultAzureCredential credential)
{
    // Query the available queues for the Service Bus namespace.
    var adminClient = new ServiceBusAdministrationClient
        ("<your_namespace>.servicebus.windows.net", credential);
    var queueNames = new List<string>();

    // Because the result is async, the queue names need to be captured
    // to a standard list to avoid async calls when registering. Failure to
    // do so results in an error with the services collection.
    await foreach (QueueProperties queue in adminClient.GetQueuesAsync())
    {
        queueNames.Add(queue.Name);
    }

    return queueNames;
}

I koden ovan:

Key Vault-hemligheter, Blob Storage- och Service Bus-klienter registreras med hjälp av AddSecretClient AddBlobServiceClient AddServiceBusClientWithNamespace, respektive . Argumenten Uri- och string-typ skickas. Information om hur du undviker att uttryckligen ange dessa URL:er finns i avsnittet Lagra konfiguration separat från kod .
DefaultAzureCredential används för att uppfylla argumentkravet TokenCredential för varje registrerad klient. När en av klienterna skapas DefaultAzureCredential används den för att autentisera.
Service Bus-underklienter registreras för varje kö i tjänsten med hjälp av de underordnade och motsvarande alternativtyperna. Könamnen för underklienterna hämtas med en separat metod utanför tjänstregistreringen GetQueuesAsync eftersom metoden måste köras asynkront.
En Azure OpenAI-klient registreras med hjälp av en anpassad klientfabrik via AddClient metoden, vilket ger kontroll över hur en klientinstans skapas. Anpassade klientfabriker är användbara i följande fall:
- Du måste använda andra beroenden under klientkonstruktionen.
- Det finns ingen registreringstilläggsmetod för den tjänstklient som du vill registrera.

Använda de registrerade klienterna

Med de registrerade klienterna, enligt beskrivningen i avsnittet Registrera klienter och underklienter , kan du nu använda dem. I följande exempel används konstruktorinmatning för att hämta Blob Storage-klienten och en fabrik för Service Bus-avsändarunderklienter i en ASP.NET Core API-styrenhet:

[ApiController]
[Route("[controller]")]
public class MyApiController : ControllerBase
{
    private readonly BlobServiceClient _blobServiceClient;
    private readonly ServiceBusSender _serviceBusSender;
  
    public MyApiController(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
        _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("myQueueName");
    }
  
    [HttpGet]
    public async Task<IEnumerable<string>> Get()
    {
        BlobContainerClient containerClient = 
            _blobServiceClient.GetBlobContainerClient("demo");
        var results = new List<string>();

        await foreach (BlobItem blob in containerClient.GetBlobsAsync())
        {
            results.Add(blob.Name);
        }

        return results.ToArray();
    }
}

Lagra konfiguration separat från kod

I avsnittet Registrera klienter och underklienter skickade du uttryckligen variablerna Uri-typ till klientkonstruktorerna. Den här metoden kan orsaka problem när du kör kod mot olika miljöer under utveckling och produktion. .NET-teamet föreslår att sådana konfigurationer lagras i miljöberoende JSON-filer. Du kan till exempel ha en appettings. Development.json fil som innehåller inställningar för utvecklingsmiljön. En annan appettings. Production.json fil skulle innehålla inställningar för produktionsmiljön och så vidare. Filformatet är:

{
  "AzureDefaults": {
    "Diagnostics": {
      "IsTelemetryDisabled": false,
      "IsLoggingContentEnabled": true
    },
    "Retry": {
      "MaxRetries": 3,
      "Mode": "Exponential"
    }
  },
  "KeyVault": {
    "VaultUri": "https://mykeyvault.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://mydemoaccount.storage.windows.net"
  }
}

Du kan lägga till alla egenskaper från ClientOptions klassen i JSON-filen. Inställningarna i JSON-konfigurationsfilen kan hämtas med .IConfiguration

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    clientBuilder.UseCredential(new DefaultAzureCredential());

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("Storage"));

    clientBuilder.AddServiceBusClientWithNamespace(
        builder.Configuration["ServiceBus:Namespace"]);

    clientBuilder.UseCredential(new DefaultAzureCredential());

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

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.AddHostedService<Worker>();
        services.AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddSecretClient(
                hostContext.Configuration.GetSection("KeyVault"));

            clientBuilder.AddBlobServiceClient(
                hostContext.Configuration.GetSection("Storage"));

            clientBuilder.AddServiceBusClientWithNamespace(
                hostContext.Configuration["ServiceBus:Namespace"]);

            clientBuilder.UseCredential(new DefaultAzureCredential());

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

I föregående JSON-exempel:

Nyckelnamnen på den översta nivån, AzureDefaults, KeyVault, ServiceBusoch Storage, är godtyckliga. Alla andra nyckelnamn har betydelse och JSON-serialisering utförs på ett skiftlägesokänsligt sätt.
Objektliteralen AzureDefaults.Retry :
- Representerar konfigurationsinställningarna för återförsöksprinciper.
- Motsvarar egenskapen Retry . I objektliteralen MaxRetries hittar du nyckeln, som motsvarar MaxRetries egenskapen.
Nyckelvärdena KeyVault:VaultUri, ServiceBus:Namespaceoch Storage:ServiceUri mappas till argumenten Uri- och string-typ för överlagringarna Azure.Security.KeyVault.Secrets.SecretClient.SecretClient(Uri, TokenCredential, SecretClientOptions), Azure.Messaging.ServiceBus.ServiceBusClient.ServiceBusClient(String)och Azure.Storage.Blobs.BlobServiceClient.BlobServiceClient(Uri, TokenCredential, BlobClientOptions) konstruktorn. Varianterna TokenCredential av konstruktorerna används eftersom ett standardvärde TokenCredential anges via metodanropet Microsoft.Extensions.Azure.AzureClientFactoryBuilder.UseCredential(TokenCredential) .

Konfigurera flera tjänstklienter med olika namn

Anta att du har två lagringskonton: ett för privat information och ett annat för offentlig information. Din app överför data från allmänheten till det privata lagringskontot efter en viss åtgärd. Du måste ha två lagringstjänstklienter. Om du vill särskilja dessa två klienter använder du WithName tilläggsmetoden:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        builder.Configuration.GetSection("PublicStorage"));

    clientBuilder.AddBlobServiceClient(
            builder.Configuration.GetSection("PrivateStorage"))
        .WithName("PrivateStorage");
});

Använd till exempel en ASP.NET Core-styrenhet och få åtkomst till den namngivna tjänstklienten med hjälp av IAzureClientFactory<TClient> gränssnittet:

public class HomeController : Controller
{
    private readonly BlobServiceClient _publicStorage;
    private readonly BlobServiceClient _privateStorage;

    public HomeController(
        BlobServiceClient defaultClient,
        IAzureClientFactory<BlobServiceClient> clientFactory)
    {
        _publicStorage = defaultClient;
        _privateStorage = clientFactory.CreateClient("PrivateStorage");
    }
}

Den namnlösa tjänstklienten är fortfarande tillgänglig på samma sätt som tidigare. Namngivna klienter är additiva.

Konfigurera en ny återförsöksprincip

Vid något tillfälle kanske du vill ändra standardinställningarna för en 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. Anta att du har följande appsettings.json fil i ditt ASP.NET Core-projekt:

{
  "AzureDefaults": {
    "Retry": {
      "maxRetries": 3
    }
  },
  "KeyVault": {
    "VaultUri": "https://mykeyvault.vault.azure.net"
  },
  "ServiceBus": {
    "Namespace": "<your_namespace>.servicebus.windows.net"
  },
  "Storage": {
    "ServiceUri": "https://store1.storage.windows.net"
  },
  "CustomStorage": {
    "ServiceUri": "https://store2.storage.windows.net"
  }
}

Du kan ändra återförsöksprincipen så att den passar dina behov så här:

builder.Services.AddAzureClients(clientBuilder =>
{
    // Establish the global defaults
    clientBuilder.ConfigureDefaults(
        builder.Configuration.GetSection("AzureDefaults"));
    clientBuilder.UseCredential(new DefaultAzureCredential());

    // A Key Vault Secrets client using the global defaults
    clientBuilder.AddSecretClient(
        builder.Configuration.GetSection("KeyVault"));

    // A Blob Storage client with a custom retry policy
    clientBuilder.AddBlobServiceClient(
            builder.Configuration.GetSection("Storage"))
        .ConfigureOptions(options => options.Retry.MaxRetries = 10);

    clientBuilder.AddServiceBusClientWithNamespace(
            builder.Configuration["ServiceBus:Namespace"])
        .ConfigureOptions(options => options.RetryOptions.MaxRetries = 10);

    // A named storage client with a different custom retry policy
    clientBuilder.AddBlobServiceClient(
            builder.Configuration.GetSection("CustomStorage"))
        .WithName("CustomStorage")
        .ConfigureOptions(options =>
        {
            options.Retry.Mode = Azure.Core.RetryMode.Exponential;
            options.Retry.MaxRetries = 5;
            options.Retry.MaxDelay = TimeSpan.FromSeconds(120);
        });
});

Du kan också placera åsidosättningar av återförsöksprinciper i filen appsettings.json :

{
  "KeyVault": {
    "VaultUri": "https://mykeyvault.vault.azure.net",
    "Retry": {
      "maxRetries": 10
    }
  }
}

Dela via