Menggunakan Azure SDK untuk .NET di aplikasi ASP.NET Core

Azure SDK untuk .NET memungkinkan aplikasi ASP.NET Core untuk diintegrasikan dengan banyak layanan Azure yang berbeda. Dalam artikel ini, Anda akan mempelajari praktik terbaik dan langkah-langkah untuk mengadopsi Azure SDK untuk .NET di aplikasi ASP.NET Core Anda. Anda akan mempelajari cara:

• Mendaftarkan layanan untuk injeksi dependensi.
• Autentikasi ke Azure tanpa menggunakan kata sandi atau rahasia.
• Terapkan konfigurasi terpusat dan standar.
• Konfigurasikan masalah aplikasi web umum seperti pengelogan dan percobaan ulang.

Menjelajahi pustaka klien Azure SDK umum

ASP.NET Aplikasi inti yang terhubung ke layanan Azure umumnya bergantung pada pustaka klien Azure SDK berikut:

• Microsoft.Extensions.Azure menyediakan metode pembantu untuk mendaftarkan klien dengan kumpulan layanan injeksi dependensi dan menangani berbagai kekhawatiran bagi Anda, seperti menyiapkan pengelogan, menangani masa pakai layanan DI, dan manajemen kredensial autentikasi.
• Azure.Identity memungkinkan dukungan autentikasi ID Microsoft Entra di seluruh Azure SDK. Ini menyediakan serangkaian implementasi TokenCredential untuk membangun klien Azure SDK yang mendukung autentikasi Microsoft Entra.
• Azure.<service-namespace> pustaka, seperti Azure.Storage.Blobs dan Azure.Messaging.ServiceBus, menyediakan klien layanan dan jenis lainnya untuk membantu Anda terhubung dan menggunakan layanan Azure tertentu. Untuk inventaris lengkap pustaka ini, lihat Pustaka menggunakan Azure.Core.

Di bagian depan, Anda akan menjelajahi cara mengimplementasikan aplikasi ASP.NET Core yang menggunakan pustaka ini.

Mendaftarkan klien Azure SDK dengan koleksi layanan DI

Pustaka klien Azure SDK for .NET menyediakan klien layanan untuk menyambungkan aplikasi Anda ke layanan Azure seperti Azure Blob Storage dan Azure Key Vault. Daftarkan layanan ini di dalam container dependensi pada file Program.cs aplikasi Anda agar dapat diakses melalui dependency injection.

Selesaikan langkah-langkah berikut untuk mendaftarkan layanan yang Anda butuhkan:

1. Tambahkan paket Microsoft.Extensions.Azure:

   dotnet add package Microsoft.Extensions.Azure
   

2. Tambahkan paket klien layanan yang relevan Azure.* :

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

3. Dalam file Program.cs aplikasi Anda, gunakan metode ekstensi AddAzureClients dari pustaka Microsoft.Extensions.Azure untuk mendaftarkan klien agar dapat berkomunikasi dengan setiap layanan Azure. Beberapa pustaka klien menyediakan subklien tambahan untuk kelompok tertentu dari fungsi layanan Azure. Anda dapat mendaftarkan subklien tersebut untuk injeksi dependensi melalui metode ekstensi AddClient.

   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);
       }
   
       // Register a shared credential for Microsoft Entra ID authentication
       clientBuilder.UseCredential(new DefaultAzureCredential());
   });
   

4. Masukkan klien terdaftar ke komponen aplikasi ASP.NET Core, layanan, atau titik akhir API Anda:

   • Minimal API
   • Blazor

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

Untuk informasi selengkapnya, lihat Injeksi dependensi dengan Azure SDK untuk .NET.

Mengautentikasi menggunakan ID Microsoft Entra

Autentikasi berbasis token dengan ID Microsoft Entra adalah pendekatan yang disarankan untuk mengautentikasi permintaan ke layanan Azure. Untuk mengotorisasi permintaan tersebut, kontrol akses berbasis peran Azure (RBAC) mengelola akses ke sumber daya Azure berdasarkan identitas Microsoft Entra pengguna dan peran yang ditetapkan.

Gunakan pustaka Azure Identity untuk dukungan autentikasi berbasis token yang disebutkan di atas. Pustaka menyediakan kelas seperti DefaultAzureCredential untuk menyederhanakan konfigurasi koneksi aman. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode mana yang harus digunakan saat runtime. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan. Kunjungi bagian Autentikasi azure SDK untuk dokumen .NET untuk detail selengkapnya tentang topik ini.

1. Tambahkan paket Azure.Identity:

   dotnet add package Azure.Identity
   

2. Dalam file Program.cs aplikasi Anda, panggil metode ekstensi UseCredential dari pustaka Microsoft.Extensions.Azure guna menetapkan instans bersama DefaultAzureCredential untuk semua klien layanan Azure terdaftar.

   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);
       }
   
       // Register a shared credential for Microsoft Entra ID authentication
       clientBuilder.UseCredential(new DefaultAzureCredential());
   });
   

   DefaultAzureCredential menemukan kredensial yang tersedia di lingkungan saat ini dan menggunakannya untuk mengautentikasi ke layanan Azure. Untuk urutan dan lokasi di mana DefaultAzureCredential memindai kredensial, lihat Gambaran Umum DefaultAzureCredential. Menggunakan instans berbagi DefaultAzureCredential memastikan penggunaan cache token yang mendasar, yang meningkatkan ketahanan dan performa aplikasi dengan mengurangi permintaan token baru.

Menerapkan konfigurasi

Klien layanan Azure SDK mendukung konfigurasi untuk mengubah perilaku default mereka. Ada dua cara untuk mengonfigurasi klien layanan:

• File konfigurasi JSON umumnya merupakan pendekatan yang direkomendasikan karena menyederhanakan pengelolaan perbedaan dalam penyebaran aplikasi antar lingkungan.
• Konfigurasi kode sebaris dapat diterapkan saat Anda mendaftarkan klien layanan. Misalnya, di bagian Daftarkan klien dan subkelas , Anda secara eksplisit meneruskan variabel URI ke konstruktor klien.

IConfiguration Aturan prioritas dihormati oleh Microsoft.Extensions.Azure metode ekstensi, yang dirinci dalam dokumentasi Penyedia Konfigurasi.

Selesaikan langkah-langkah di bagian berikut untuk memperbarui aplikasi Anda guna menggunakan konfigurasi file JSON untuk lingkungan yang sesuai. appsettings.Development.json Gunakan file untuk pengaturan pengembangan dan appsettings.Production.json file untuk pengaturan lingkungan produksi. Anda dapat menambahkan pengaturan konfigurasi yang namanya adalah properti publik di ClientOptions kelas ke file JSON.

Mengonfigurasi layanan terdaftar

1. appsettings.<environment>.json Perbarui file di aplikasi Anda dengan konfigurasi layanan yang disorot:

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

   Dalam sampel JSON sebelumnya:

   • Nama kunci tingkat atas, KeyVault, , ServiceBusdan Storage, adalah nama arbitrer yang digunakan untuk mereferensikan bagian konfigurasi dari kode Anda. Anda akan meneruskan nama-nama ini ke AddClient metode ekstensi untuk mengonfigurasi klien tertentu. Semua nama kunci lainnya dipetakan ke opsi klien tertentu, dan serialisasi JSON dilakukan dengan cara yang tidak membedakan huruf besar/kecil.
   • Nilai kunci KeyVault:VaultUri, ServiceBus:Namespace, dan Storage:ServiceUri dipetakan ke argumen overload konstruktor SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String), dan BlobServiceClient(Uri, TokenCredential, BlobClientOptions). TokenCredential varian-varian konstruktor digunakan karena default TokenCredential diatur melalui UseCredential(TokenCredential) pemanggilan metode.

2. Perbarui file Program.cs untuk mengambil konfigurasi file JSON menggunakan IConfiguration dan meneruskannya ke pendaftaran layanan Anda.

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

Mengonfigurasi pengaturan awal dan pengulangan Azure

Anda mungkin ingin mengubah konfigurasi klien Azure default secara global atau untuk klien layanan tertentu. Misalnya, Anda mungkin menginginkan pengaturan coba lagi yang berbeda atau menggunakan versi API layanan yang berbeda. Anda dapat mengatur pengaturan coba lagi secara global atau per layanan.

1. Perbarui file konfigurasi Anda untuk mengatur pengaturan Azure default, seperti kebijakan coba lagi default baru yang akan digunakan semua klien Azure terdaftar:

   {
     "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. Di dalam file Program.cs, panggil metode ekstensi ConfigureDefaults untuk mengambil pengaturan default dan menerapkannya ke klien layanan Anda:

   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);
       }
   
       clientBuilder.UseCredential(new DefaultAzureCredential());
   
       // Set up any default settings
       clientBuilder.ConfigureDefaults(
           builder.Configuration.GetSection("AzureDefaults"));
   });
   

Mengonfigurasi pengelogan

Pustaka klien Azure SDK untuk .NET dapat mencatat operasi pustaka klien untuk memantau permintaan dan respons terhadap layanan Azure. Pustaka klien juga dapat mencatat berbagai peristiwa lain, termasuk percobaan ulang, pengambilan ulang token, dan peristiwa khusus dari setiap layanan dari berbagai klien. Saat Anda mendaftarkan klien Azure SDK menggunakan metode ekstensi AddAzureClients, AzureEventSourceLogForwarder terdaftar dengan kontainer dependensi injeksi. AzureEventSourceLogForwarder meneruskan pesan log dari sumber peristiwa Azure SDK ke ILoggerFactory, memungkinkan Anda menggunakan konfigurasi logging ASP.NET Core standar.

Tabel berikut ini menggambarkan bagaimana EventLevel Azure SDK untuk .NET memetakan ke LogLevel ASP.NET Core. Untuk informasi selengkapnya tentang topik ini dan skenario lainnya, lihat Pengelogan dengan Azure SDK untuk .NET dan Injeksi Dependensi dengan Azure SDK untuk .NET.

Anda dapat mengubah tingkat log default dan pengaturan lain menggunakan konfigurasi JSON yang sama yang diuraikan di bagian konfigurasi autentikasi . Misalnya, ubah tingkat log ke ServiceBusClientDebug dengan menetapkan kunci Logging:LogLevel:Azure.Messaging.ServiceBus sebagai berikut:

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