Aracılığıyla paylaş

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

  • Makale

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. Böyle bir türü kabul eden tüm kayıtlı istemcilerin kimliğini doğrulamak için kullanılacak bir TokenCredential tür yapılandırmak için Azure.Identity paketini yükleyin:

    dotnet add package Azure.Identity

Tanıtım amacıyla, bu makaledeki örnek kod Key Vault Gizli Dizileri, Blob Depolama, Service Bus ve Azure OpenAI kitaplıklarını 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 Azure.AI.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.Extensions.Hosting ad alanlarının Microsoft.AspNetCore.Builder 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 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;
}

Önceki kodda:

  • Key Vault Gizli Dizileri, Blob Depolama ve Service Bus istemcileri sırasıyla ve AddBlobServiceClient AddServiceBusClientWithNamespacekullanılarak AddSecretClientkaydedilir. 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.
  • DefaultAzureCredential , her kayıtlı istemci için TokenCredential bağımsız değişken gereksinimini karşılamak için kullanılır. İstemcilerden biri oluşturulduğunda, DefaultAzureCredential kimlik doğrulaması için kullanılır.
  • 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.
  • Azure OpenAI istemcisi, bir istemci örneğinin nasıl oluşturulduğu üzerinde denetim sağlayan yöntemi aracılığıyla AddClient özel bir istemci fabrikası kullanılarak kaydedilir. Ö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"]);

    clientBuilder.UseCredential(new DefaultAzureCredential());

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

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.