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

Makale
09/09/2023

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:

Projenize Microsoft.Extensions.Azure paketini yükleyin:
```
dotnet add package Microsoft.Extensions.Azure
```
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 ve Service Bus 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

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

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

List<string> queueNames = await GetQueueNames();

builder.Services.AddAzureClients(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");
    clientBuilder.UseCredential(new DefaultAzureCredential());

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

WebApplication app = builder.Build();

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

List<string> queueNames = await GetQueueNames();

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddAzureClients(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");
            clientBuilder.UseCredential(new DefaultAzureCredential());

            // Register subclients for Service Bus
            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);
            }
        });
    }).Build();

await host.RunAsync();

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

List<string> queueNames = await GetQueueNames();

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddAzureClients(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");
            clientBuilder.UseCredential(new DefaultAzureCredential());

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

await host.RunAsync();

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

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 almak için oluşturucu ekleme kullanılmıştır:

[ApiController]
[Route("[controller]")]
public class MyApiController : ControllerBase
{
    private readonly BlobServiceClient _blobServiceClient;
  
    public MyApiController(BlobServiceClient blobServiceClient)
    {
        _blobServiceClient = blobServiceClient;
    }
  
    [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"));
});

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

Yukarıdaki JSON örneğinde:

, , KeyVaultServiceBusve Storageüst düzey anahtar adları AzureDefaultsrastgeledir. Diğer tüm anahtar adları anlamlıdır ve JSON serileştirme büyük/küçük harfe duyarsız bir şekilde gerçekleştirilir.
Nesne AzureDefaults.Retry değişmez değeri:
- Yeniden deneme ilkesi yapılandırma ayarlarını temsil eder.
- özelliğine Retry karşılık gelir. Bu nesne değişmez değeri içinde, özelliğine MaxRetriesMaxRetries karşılık gelen anahtarı bulursunuz.
, ve anahtar değerleri sırasıyla , Azure.Messaging.ServiceBus.ServiceBusClient.ServiceBusClient(String)ve oluşturucu aşırı yüklemelerinin Azure.Security.KeyVault.Secrets.SecretClient.SecretClient(Uri, TokenCredential, SecretClientOptions)- ve stringAzure.Storage.Blobs.BlobServiceClient.BlobServiceClient(Uri, TokenCredential, BlobClientOptions) -typed bağımsız değişkenleriyle eşlerUri.Storage:ServiceUriServiceBus:NamespaceKeyVault:VaultUri TokenCredential Yöntem çağrısı aracılığıyla varsayılan TokenCredential ayarlandığı için oluşturucuların Microsoft.Extensions.Azure.AzureClientFactoryBuilder.UseCredential(TokenCredential) değişkenleri kullanılır.

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

Share via