Aracılığıyla paylaş

ASP.NET Core uygulamalarında .NET için Azure SDK'sını kullanma

.NET için Azure SDK, ASP.NET Core uygulamalarının birçok farklı Azure hizmetiyle tümleştirilmesini sağlar. Bu makalede, ASP.NET Core uygulamalarınızda .NET için Azure SDK'yı benimsemeye yönelik en iyi yöntemleri ve adımları öğreneceksiniz. Nasıl yapılacağını öğrenin:

  • Bağımlılık ekleme için hizmetleri kaydedin.
  • Parola veya gizli dizi kullanmadan Azure'da kimlik doğrulaması.
  • Merkezi, standartlaştırılmış yapılandırmayı uygulayın.
  • Günlük kaydedilmesi ve yeniden denemeler gibi yaygın web uygulaması ihtiyaçlarını yapılandırın.

Yaygın Azure SDK istemci kitaplıklarını keşfetme

Azure hizmetlerine bağlanan ASP.NET Core uygulamaları genellikle aşağıdaki Azure SDK istemci kitaplıklarına bağlıdır:

  • Microsoft.Extensions.Azure, istemcileri bağımlılık ekleme hizmet koleksiyonuna kaydetmek için yardımcı yöntemler sağlar ve sizin için günlüğe kaydetme, DI hizmet yaşam sürelerini işleme ve kimlik doğrulama kimlik bilgisi yönetimi gibi çeşitli konuları ele alır.
  • Azure.Identity , Azure SDK genelinde Microsoft Entra Id kimlik doğrulaması desteğini etkinleştirir. Microsoft Entra kimlik doğrulamasını TokenCredential destekleyen Azure SDK istemcileri oluşturmak için bir dizi uygulama sağlar.
  • Azure.<service-namespace>azure.Storage.Blobs ve Azure.Messaging.ServiceBus gibi kitaplıklar, belirli Azure hizmetlerine bağlanmanıza ve bunları kullanmanıza yardımcı olmak için hizmet istemcileri ve diğer türleri sağlar. Bu kitaplıkların tam envanteri için bkz . Azure.Core kullanan kitaplıklar.

İlerideki bölümlerde, bu kitaplıkları kullanan bir ASP.NET Core uygulamasının nasıl uygulandığını keşfedeceksiniz.

Azure SDK istemcilerini DI hizmet koleksiyonuna kaydetme

.NET için Azure SDK istemci kitaplıkları, uygulamanızı Azure Blob Depolama ve Azure Key Vault gibi Azure hizmetlerine bağlamak için hizmet istemcileri sağlar. Uygulamanızın Program.cs dosyasındaki bağımlılık kapsayıcısına bu hizmetleri kaydedin, böylece bağımlılık ekleme yoluyla kullanılabilir hale gelsinler.

İhtiyacınız olan hizmetleri kaydetmek için aşağıdaki adımları tamamlayın:

  1. Microsoft.Extensions.Azure paketini ekleyin:

    dotnet add package Microsoft.Extensions.Azure

  2. İlgili Azure.* hizmet istemci paketlerini ekleyin:

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

  3. Uygulamanızın Program.cs dosyasında, her Azure hizmetiyle iletişim kurmak üzere bir istemci kaydetmek için kitaplıktan AddAzureClients uzantı yöntemini çağırınMicrosoft.Extensions.Azure. Bazı istemci kitaplıkları, Azure hizmeti işlevselliğinin belirli alt grupları için ek alt istemciler sağlar. Uzantı yöntemi aracılığıyla AddClient bağımlılık ekleme için bu tür alt istemciler kaydedebilirsiniz.

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

var app = builder.Build();

  4. Kayıtlı istemcileri ASP.NET Core uygulama bileşenlerinize, hizmetlerinize veya API uç noktanıza ekleyin:

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

Daha fazla bilgi için bkz . .NET için Azure SDK ile bağımlılık ekleme.

Microsoft Entra Id kullanarak kimlik doğrulaması

Microsoft Entra Id ile belirteç tabanlı kimlik doğrulaması, Azure hizmetlerine yönelik isteklerin kimliğini doğrulamak için önerilen yaklaşımdır. Bu istekleri yetkilendirmek için Azure rol tabanlı erişim denetimi (RBAC), kullanıcının Microsoft Entra kimliğine ve atanmış rollerine göre Azure kaynaklarına erişimi yönetir.

Yukarıda belirtilen belirteç tabanlı kimlik doğrulama desteği için Azure Kimlik kitaplığını kullanın. Kitaplık, güvenli bağlantıları yapılandırmayı basitleştirmek için gibi DefaultAzureCredential sınıflar sağlar. DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler. Bu yaklaşım, uygulamanızın ortama özgü kod uygulamadan farklı ortamlarda (yerel ve üretim) farklı kimlik doğrulama yöntemleri kullanmasını sağlar. Bu konularla ilgili diğer ayrıntılar için .NET belgeleri için Azure SDK'sının Kimlik Doğrulaması bölümünü ziyaret edin.

Not

Birçok Azure hizmeti, anahtarları kullanarak istekleri yetkilendirmenize de olanak sağlar. Ancak bu yaklaşım dikkatli kullanılmalıdır. Geliştiriciler, erişim anahtarını güvenli olmayan bir konumda asla kullanıma sunmamak için dikkatli olmalıdır. Erişim anahtarına sahip olan herkes, istekleri ilişkili Azure kaynağına göre yetkileyebilir.

  1. Azure.Identity paketini ekleyin:

    dotnet add package Azure.Identity

  2. Uygulamanızın Program.cs dosyasında, tüm kayıtlı Azure hizmeti istemcileri için paylaşılan bir AddAzureClients örneği ayarlamak amacıyla Microsoft.Extensions.Azure kitaplığından DefaultAzureCredential uzantı yöntemini çağırın.

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

var app = builder.Build();

    DefaultAzureCredential geçerli ortamdaki kullanılabilir kimlik bilgilerini bulur ve Bunları Kullanarak Azure hizmetlerinde kimlik doğrulaması yapar. Kimlik bilgilerini tarayan DefaultAzureCredential'nin sıra ve konumları için DefaultAzureCredential'a genel bakış'a bakın. Paylaşılan DefaultAzureCredential bir örneğin kullanılması, temel alınan belirteç önbelleğinin kullanılmasını sağlar ve bu da yeni belirteç için daha az istek nedeniyle uygulama dayanıklılığını ve performansını artırır.

Yapılandırmaları uygulama

Azure SDK hizmet istemcileri, varsayılan davranışlarını değiştirmek için yapılandırmaları destekler. Hizmet istemcilerini yapılandırmanın iki yolu vardır:

  • JSON yapılandırma dosyaları genellikle önerilen yaklaşımdır çünkü ortamlar arasındaki uygulama dağıtımlarındaki farkları yönetmeyi basitleştirir.
  • Hizmet istemcisini kaydettiğinizde satır içi kod yapılandırmaları uygulanabilir. Örneğin, İstemcileri ve alt istemcileri kaydetme bölümünde, URI değişkenlerini açıkça istemci oluşturucularına geçirdiniz.

IConfiguration öncelik kurallarına, Microsoft.Extensions.Azure genişletme yöntemleri tarafından uyulur, bu yöntemler Yapılandırma Sağlayıcıları belgelerinde ayrıntılı olarak yer alır.

Uygulamanızı uygun ortamlar için JSON dosya yapılandırmasını kullanacak şekilde güncelleştirmek için aşağıdaki bölümlerde yer alan adımları tamamlayın. appsettings.Development.json Geliştirme ayarları için dosyasını ve appsettings.Production.json üretim ortamı ayarları için dosyasını kullanın. JSON dosyasına, ClientOptions sınıfında adları genel özellikler olan yapılandırma ayarları ekleyebilirsiniz.

Kayıtlı hizmetleri yapılandırma

  1. appsettings.<environment>.json Uygulamanızdaki dosyayı vurgulanan hizmet yapılandırmalarıyla güncelleştirin:

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

    Yukarıdaki JSON örneğinde:

    • En üst düzey anahtar adları, KeyVault, ServiceBusve Storage, kodunuzun yapılandırma bölümlerine başvurmak için kullanılan rastgele adlardır. Belirli bir istemciyi yapılandırmak için bu adları AddClient genişletme yöntemlerine geçireceksiniz. Diğer tüm anahtar adları belirli istemci seçenekleriyle eşlenir ve JSON serileştirme büyük/küçük harfe duyarsız bir şekilde gerçekleştirilir.
    • KeyVault:VaultUri, ServiceBus:Namespace ve Storage:ServiceUri anahtar değerleri sırasıyla, SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String) ve BlobServiceClient(Uri, TokenCredential, BlobClientOptions) oluşturucu aşırı yüklenmelerinin bağımsız değişkenleriyle eşleştirilir.

  2. Program.cs kullanarak IConfiguration JSON dosya yapılandırmalarını almak ve bunları hizmet kayıtlarınıza geçirmek için dosyayı güncelleştirin:

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

Azure varsayılanlarını ve yeniden denemelerini yapılandırma

Varsayılan Azure istemci yapılandırmalarını genel olarak veya belirli bir hizmet istemcisi için 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.

  1. Tüm kayıtlı Azure istemcilerinin kullanacağı yeni bir varsayılan yeniden deneme ilkesi gibi varsayılan Azure ayarlarını ayarlamak için yapılandırma dosyanızı güncelleştirin:

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

  2. Program.cs Dosyasında, varsayılan ayarları almak ve bunları hizmet istemcilerinize uygulamak için uzantı yöntemini çağırınConfigureDefaults:

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

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

var app = builder.Build();

Günlük kaydetmeyi yapılandırma

.NET istemci kitaplıkları için Azure SDK'sı, Azure hizmetlerine yönelik istekleri ve yanıtları izlemek için istemci kitaplığı işlemlerini günlüğe kaydedebilir. İstemci kitaplıkları ayrıca, yeniden denemeler, belirteç alma ve çeşitli istemcilerden gelen hizmete özgü olaylar da dahil olmak üzere diğer olayları günlüğe kaydedebilir. Uzantı yöntemini kullanarak bir Azure SDK istemcisi kaydettiğinizde AddAzureClientsAzureEventSourceLogForwarder , bağımlılık ekleme kapsayıcısıyla kaydedilir. Azure SDK olay kaynaklarından gelen günlük mesajlarını AzureEventSourceLogForwarder, ILoggerFactory 'e ileterek standart ASP.NET Core günlük yapılandırmasını kullanmanıza olanak tanır.

Aşağıdaki tabloda .NET EventLevel için Azure SDK'sının ASP.NET Core LogLevelile nasıl eşildiği açıklanmaktadır. Bu konular ve diğer senaryolar hakkında daha fazla bilgi için .NET için Azure SDK ile loglama ve .NET için Azure SDK ile bağımlılık enjeksiyonu kısmına bakın.

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

Varsayılan günlük düzeylerini ve diğer ayarları, aynı "kimlik doğrulamasını yapılandırma" bölümünde özetlenen JSON yapılandırmalarını kullanarak değiştirebilirsiniz. Örneğin, ServiceBusClient anahtarını aşağıdaki gibi ayarlayarak Debug günlük seviyesini Logging:LogLevel:Azure.Messaging.ServiceBus olarak değiştirin:

{
  "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"
  }
}
  • Last updated on