Aracılığıyla paylaş

.NET için Azure SDK ile bağımlılık ekleme

Bu makalede, bir .NET uygulamasına bağımlılık ekleme amacıyla .NET için en son Azure istemci kitaplıklarından Azure hizmet istemcilerinin nasıl kaydedilecekleri gösterilmektedir. Her modern .NET uygulaması, Program.cs dosyasında sağlanan yönergeleri kullanarak başlar.

Paketleri yükleme

Hizmet istemcilerini -prefixed paketinden Azure.kaydetmek ve yapılandırmak için:

  1. Projenize Microsoft.Extensions.Azure paketini yükleyin:

    dotnet add package Microsoft.Extensions.Azure

  2. paketini yükleyin:

    dotnet add package Azure.Identity

Tanıtım amacıyla, bu makaledeki örnek kod Key Vault Secrets, Blob Depolama, Service Bus ve OpenAI kütüphanelerini kullanır. Takip etmek için aşağıdaki paketleri yükleyin:

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

İstemcileri ve alt istemcileri kaydetme

Hizmet istemcisi bir Azure hizmetinin API'sine giriş noktasıdır; kitaplık kullanıcıları hizmetin sağladığı tüm işlemleri çağırabilir ve en yaygın senaryoları kolayca uygulayabilir. Api'nin tasarımını basitleştireceği durumlarda, hizmet çağrıları grupları daha küçük alt istemci türleri etrafında düzenlenebilir. Örneğin, ServiceBusClient iletileri yayımlamak için ek ServiceBusSender alt istemciler veya ServiceBusReceiver iletilerin tüketilmesi için alt istemciler kaydedebilir.

Program.cs dosyasında uzantı yöntemini çağırarak AddAzureClients her hizmet için bir istemci kaydedin. Aşağıdaki kod örnekleri ve Microsoft.AspNetCore.Builder ad alanlarının Microsoft.Extensions.Hosting uygulama oluşturucuları hakkında rehberlik sağlar.

using Azure.Identity;
using Azure.Messaging.ServiceBus;
using Azure.Messaging.ServiceBus.Administration;
using Microsoft.Extensions.Azure;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel.Primitives;

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");
    
    // AddAzureClients implicitly creates a DefaultAzureCredential instance
    // Create a credential manually to override the type or access it explicitly for DI registrations
    // This example shows credential reuse for GetQueueNames and AddClient calls downstream
    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);

    // Register a subclient for each Service Bus Queue
    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);
    }

    var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
        ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is required.");

    // Register a custom client factory
    #pragma warning disable OPENAI001 // Type is for evaluation purposes and is subject to change in future updates.
    clientBuilder.AddClient<ResponsesClient, OpenAIClientOptions>(
        (options, credential, _) => new ResponsesClient(
            "<deployment_name>",
            new BearerTokenPolicy(credential, "https://ai.azure.com/.default"),
            new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") }
        ));
    #pragma warning restore OPENAI001
});

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

Önceki kodda:

  • Key Vault Gizli Dizileri, Blob Depolama ve Service Bus istemcileri sırasıyla ve AddSecretClientAddBlobServiceClientkullanılarak AddServiceBusClientWithNamespacekaydedilir. Uri- ve string-typed bağımsız değişkenleri geçirilir. Bu URL'lerin açıkça belirtilmesinden kaçınmak için Yapılandırmayı koddan ayrı depolama bölümüne bakın.
  • Kayıtlı her müşteri, farklı bir kimlik bilgisi türü yapılandırmadığınız sürece, DefaultAzureCredential için otomatik olarak TokenCredential kullanır (örneğin, WithCredential kullanarak).
  • Service Bus alt istemcileri, hizmet üzerindeki her kuyruk için alt istemci ve ilgili seçenek türleri kullanılarak kaydedilir. Yöntemin zaman uyumsuz olarak çalıştırılması gerektiğinden, alt istemciler için kuyruk adları hizmet kaydının GetQueuesAsync dışında ayrı bir yöntem kullanılarak alınır.
  • ResponsesClient yöntemi aracılığıyla AddClient özel bir istemci fabrikası kullanılarak kaydedilir ve bu, istemci örneğinin nasıl oluşturulduğu üzerinde denetim sağlar. Özel istemci fabrikaları aşağıdaki durumlarda kullanışlıdır:
    • İstemci oluşturma sırasında diğer bağımlılıkları kullanmanız gerekir.
    • Kaydetmek istediğiniz hizmet istemcisi için bir kayıt uzantısı yöntemi yok.

Kayıtlı istemcileri kullanma

İstemcileri kaydetme ve alt istemciler bölümünde açıklandığı gibi, istemcileri kaydettirdikten sonra kullanabilirsiniz. Aşağıdaki örnekte, ASP.NET Core API denetleyicisinde Blob Depolama istemcisini ve Service Bus gönderen alt istemcilerinin fabrikasını almak için oluşturucu ekleme kullanılır:

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

Yapılandırmayı koddan ayrı depolama

İstemcileri ve alt istemcileri kaydetme bölümünde, -typed değişkenlerini istemci oluşturucularına açıkça geçirdinizUri. Bu yaklaşım, geliştirme ve üretim sırasında farklı ortamlarda kod çalıştırdığınızda sorunlara neden olabilir. .NET ekibi bu tür yapılandırmaların ortama bağımlı JSON dosyalarında depolanmasını önerir. Örneğin, bir uygulama ayarlarına sahip olabilirsiniz. Geliştirme ortamı ayarlarını içeren dosya Development.json. Başka bir uygulama ayarları. Production.json dosyada üretim ortamı ayarları vb. bulunur. Dosya biçimi:

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

Sınıfındaki ClientOptions tüm özellikleri JSON dosyasına ekleyebilirsiniz. JSON yapılandırma dosyasındaki ayarlar kullanılarak IConfigurationalınabilir.

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

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

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

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

Yukarıdaki JSON örneğinde:

Farklı adlara sahip birden çok hizmet istemcisi yapılandırma

Biri özel bilgiler, diğeri genel bilgiler için olmak üzere iki depolama hesabınız olduğunu düşünün. Uygulamanız, bir işlemden sonra verileri genel depolama hesabından özel depolama hesabına aktarır. İki depolama hizmeti istemciniz olması gerekir. Bu iki istemciyi WithName ayırt etmek için uzantı yöntemini kullanın:

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

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

Örnek olarak bir ASP.NET Core denetleyicisi kullanarak, arabirimini kullanarak adlandırılmış hizmet istemcisine erişin IAzureClientFactory<TClient> :

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

Adsız hizmet istemcisi hala öncekiyle aynı şekilde kullanılabilir. Adlandırılmış istemciler eklenir.

Yeni bir yeniden deneme ilkesi yapılandırma

Bir noktada, bir hizmet istemcisi için varsayılan ayarları değiştirmek isteyebilirsiniz. Örneğin, farklı yeniden deneme ayarları kullanmak veya farklı bir hizmet API'si sürümü kullanmak isteyebilirsiniz. Yeniden deneme ayarlarını genel olarak veya hizmet başına olarak ayarlayabilirsiniz. ASP.NET Core projenizde aşağıdaki appsettings.json dosyanızın olduğunu varsayalım:

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

Yeniden deneme ilkesini gereksinimlerinize uyacak şekilde değiştirebilirsiniz:

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

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

Yeniden deneme ilkesi geçersiz kılmalarını appsettings.json dosyasına da yerleştirebilirsiniz:

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

Ayrıca bkz.

  • Last updated on