ringkasan integrasi .NET AspireAzure

Azure adalah platform cloud paling populer untuk membangun dan menyebarkan aplikasi .NET. SDK Azure untuk .NET memungkinkan manajemen dan penggunaan layanan Azure yang mudah. .NET Aspire menyediakan serangkaian integrasi dengan layanan Azure, di mana Anda bebas menambahkan sumber daya baru atau terhubung ke yang sudah ada. Artikel ini merinci beberapa aspek umum dari semua integrasi Azure dalam .NET Aspire dan bertujuan untuk membantu Anda memahami cara menggunakannya.

Tambahkan sumber daya Azure

Semua integrasi hosting .NET AspireAzure mengekspos sumber daya Azure dan berdasarkan konvensi ditambahkan menggunakan API AddAzure*. Saat Anda menambahkan sumber daya ini ke host aplikasi .NET Aspire Anda, sumber daya tersebut mewakili layanan Azure. API AddAzure* mengembalikan IResourceBuilder<T> di mana T adalah jenis sumber daya Azure. Antarmuka IResourceBuilder<T> (penyusun) ini menyediakan API fasih yang memungkinkan Anda mengonfigurasi sumber daya Azure yang mendasar dalam model aplikasi . Ada API untuk menambahkan sumber daya Azure baru, menandai sumber daya sebagai yang ada, dan mengonfigurasi bagaimana sumber daya berperilaku dalam berbagai konteks eksekusi.

Pengalaman pengembang yang khas

Saat host aplikasi .NET Aspire Anda berisi sumber daya Azure, dan Anda menjalankannya secara lokal (pengalaman pengembang tipe F5 atau dotnet run), sumber daya Azure disediakan dalam langganan Azure Anda. Ini memungkinkan Anda sebagai pengembang untuk men-debug terhadapnya secara lokal dalam konteks host aplikasi Anda.

.NET .NET Aspire bertujuan untuk meminimalkan biaya dengan menggunakan secara default Basic atau StandardStock Keeping Unit (SKU) untuk Azure integrasi. Meskipun default yang masuk akal ini disediakan, Anda dapat menyesuaikan sumber daya Azure sesuai dengan kebutuhan Anda. Selain itu, beberapa integrasi mendukung emulator atau kontainer , yang berguna untuk pengembangan, pengujian, dan penelusuran kesalahan lokal. Secara default, saat Anda menjalankan aplikasi secara lokal, sumber daya Azure menggunakan layanan Azure aktual. Namun, Anda dapat mengonfigurasinya untuk menggunakan emulator atau kontainer lokal, menghindari biaya yang terkait dengan layanan Azure aktual selama pengembangan lokal.

Emulator lokal

Beberapa layanan Azure dapat ditimulasi untuk dijalankan secara lokal. Saat ini, .NET Aspire mendukung emulator Azure berikut:

Agar sumber daya Azure Anda menggunakan emulator lokal, rantai panggilan metode RunAsEmulator pada penyusun sumber daya Azure. Metode ini mengonfigurasi sumber daya Azure untuk menggunakan emulator lokal alih-alih layanan Azure aktual.

Wadah lokal

Beberapa sumber daya Azure dapat diganti secara lokal menggunakan kontainer sumber terbuka atau lokal. Untuk mengganti sumber daya Azure secara lokal dalam kontainer, rantai panggilan ke metode RunAsContainer pada penyusun sumber daya Azure. Metode ini mengonfigurasi sumber daya Azure untuk menggunakan versi kontainer layanan untuk pengembangan dan pengujian lokal, bukan layanan Azure aktual.

Saat ini, .NET Aspire mendukung layanan Azure berikut sebagai kontainer:

Memahami API integrasi Azure

.NET .NET Aspirekekuatan terletak pada kemampuannya untuk menyediakan siklus kerja pengembang yang luar biasa. Integrasi Azure tidak ada bedanya. Mereka menyediakan serangkaian API dan pola umum yang dibagikan di semua sumber daya Azure. API dan pola ini dirancang untuk memudahkan bekerja dengan sumber daya Azure secara konsisten.

Di bagian kontainer sebelumnya, Anda melihat cara menjalankan layanan Azure secara lokal dalam kontainer. Jika Anda terbiasa dengan .NET.NET Aspire, Anda mungkin bertanya-tanya bagaimana memanggil AddAzureRedis("redis").RunAsContainer() untuk mendapatkan kontainer docker.io/library/redis lokal berbeda dari AddRedis("redis")—karena keduanya menghasilkan kontainer lokal yang sama.

Jawabannya adalah bahwa tidak ada perbedaan saat berjalan secara lokal. Namun, ketika dipublikasikan, Anda mendapatkan sumber daya yang berbeda:

Hal yang sama berlaku untuk layanan SQL dan PostgreSQL:

Untuk informasi selengkapnya tentang perbedaan antara mode jalankan dan terbitkan, lihat host aplikasi .NET.NET Aspire: Konteks eksekusi.

API untuk mengekspresikan sumber daya Azure dalam mode yang berbeda

Penyusun aplikasi terdistribusi, bagian dari host aplikasi , menggunakan pola penyusun untuk AddAzure* sumber daya ke model aplikasi . Pengembang dapat mengonfigurasi sumber daya ini dan menentukan perilakunya dalam konteks eksekusi yang berbeda. Azure integrasi hosting menyediakan API untuk menentukan bagaimana sumber daya ini harus "diterbitkan" dan "dijalankan."

Saat host aplikasi dijalankan, konteks eksekusi digunakan untuk menentukan apakah host aplikasi dalam mode Run atau Publish. Konvensi penamaan untuk API ini menunjukkan tindakan yang dimaksudkan untuk sumber daya.

Tabel berikut ini meringkas konvensi penamaan yang digunakan untuk mengekspresikan sumber daya Azure:

Untuk informasi selengkapnya tentang mode eksekusi, lihat konteks Eksekusi .

Kasus penggunaan API pada mode operasional umum

Gunakan RunAsExisting saat Anda perlu berinteraksi secara dinamis dengan sumber daya yang ada selama runtime tanpa perlu menyebarkan atau memperbaruinya. Gunakan PublishAsExisting saat mendeklarasikan sumber daya yang ada sebagai bagian dari konfigurasi penyebaran, memastikan cakupan dan izin yang benar diterapkan. Terakhir, gunakan AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) saat mendeklarasikan sumber daya yang ada di kedua konfigurasi, dengan persyaratan untuk membuat parameter referensi.

Anda dapat mengkueri apakah sumber daya ditandai sebagai sumber daya yang sudah ada, dengan memanggil metode ekstensi IsExisting(IResource) pada IResource. Untuk informasi selengkapnya, lihat Menggunakan sumber daya Azure yang ada.

Gunakan sumber daya Azure yang ada

.NET Aspire menyediakan dukungan untuk mereferensikan sumber daya Azure yang ada. Anda menandai sumber daya yang ada melalui API PublishAsExisting, RunAsExisting, dan AsExisting. API ini memungkinkan pengembang untuk mereferensikan sumber daya Azure yang sudah disebarkan, mengonfigurasinya, dan menghasilkan manifes penyebaran yang sesuai menggunakan templat Bicep.

Sumber daya yang ada yang dirujuk dengan API ini dapat ditingkatkan dengan penetapan peran dan penyesuaian lain yang tersedia melalui kemampuan infrastruktur sebagai kode dari . API ini terbatas pada penggunaan sumber daya Azure yang hanya bisa disebarkan menggunakan templat Bicep.

Mengonfigurasi sumber daya Azure yang ada untuk mode eksekusi

Metode RunAsExisting digunakan ketika aplikasi terdistribusi dijalankan dalam mode "jalankan". Dalam mode ini, diasumsikan bahwa sumber daya Azure yang direferensikan sudah ada dan terintegrasi dengannya selama eksekusi tanpa menyediakan sumber daya. Untuk menandai sumber daya Azure sebagai yang sudah ada, panggil metode RunAsExisting pada penyusun sumber daya. Pertimbangkan contoh berikut:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Kode sebelumnya:

• Membuat instans builder baru.
• Menambahkan parameter bernama existingServiceBusName ke builder.
• Menambahkan sumber daya Azure Service Bus yang bernama messaging ke builder.
• Memanggil metode RunAsExisting pada penyusun sumber daya serviceBus, meneruskan parameter existingServiceBusName—atau, Anda dapat menggunakan kelebihan parameter string.
• Menambahkan antrean bernama queue ke sumber daya serviceBus.

Secara default, referensi parameter Bus Layanan diasumsikan berada dalam grup sumber daya Azure yang sama. Namun, jika berada dalam grup sumber daya yang berbeda, Anda dapat meneruskan grup sumber daya secara eksplisit sebagai parameter untuk menentukan pengelompokan sumber daya yang sesuai dengan benar.

Mengonfigurasi sumber daya Azure yang ada untuk mode penerbitan

Metode PublishAsExisting digunakan dalam mode "terbitkan" ketika niatnya adalah untuk mendeklarasikan dan mereferensikan sumber daya Azure yang sudah ada selama mode penerbitan. API ini memfasilitasi pembuatan manifes dan templat yang menyertakan definisi sumber daya yang memetakan sumber daya yang ada di Bicep.

Untuk menandai sumber daya Azure sebagai sudah ada untuk mode "terbitkan", panggil metode PublishAsExisting pada penyusun sumber daya. Pertimbangkan contoh berikut:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Kode sebelumnya:

• Membuat instans builder baru.
• Menambahkan parameter bernama existingServiceBusName ke pembangun.
• Menambahkan sumber daya Azure Service Bus yang bernama messaging ke builder.
• Memanggil metode PublishAsExisting pada penyusun sumber daya serviceBus, meneruskan parameter existingServiceBusName—atau, Anda dapat menggunakan kelebihan parameter string.
• Menambahkan antrean bernama queue ke sumber daya serviceBus.

Setelah host aplikasi dijalankan dalam mode publikasi, file manifes yang dihasilkan akan menyertakan parameter existingResourceName, yang dapat digunakan untuk mereferensikan sumber daya Azure yang ada. Pertimbangkan cuplikan parsial file manifes yang dihasilkan berikut:

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Untuk informasi selengkapnya tentang file manifes, lihat format manifes .NET.NET Aspire untuk pengembang alat penyebaran.

Selain itu, templat Bicep yang dihasilkan mencakup parameter existingResourceName, yang dapat digunakan untuk mereferensikan sumber daya Azure yang ada. Pertimbangkan templat Bicep yang dihasilkan berikut ini:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Untuk informasi selengkapnya tentang templat Bicep yang dihasilkan, lihat Infrastruktur sebagai kode dan pertimbangkan API penerbitan lainnya.

Mengonfigurasi sumber daya Azure yang ada di semua mode

Metode AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) digunakan ketika aplikasi terdistribusi berjalan dalam mode "jalankan" atau "terbitkan". Karena metode AsExisting beroperasi dalam kedua skenario, metode hanya mendukung referensi parameter ke nama sumber daya atau nama grup sumber daya. Pendekatan ini membantu mencegah penggunaan sumber daya yang sama di lingkungan pengujian dan produksi.

Untuk menandai sumber daya Azure sebagai yang sudah ada, panggil metode AsExisting pada penyusun sumber daya. Pertimbangkan contoh berikut:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Kode sebelumnya:

• Membuat instans builder baru.
• Menambahkan parameter bernama existingServiceBusName ke builder.
• Menambahkan sumber daya Azure Service Bus yang bernama messaging ke builder.
• Memanggil metode AsExisting pada penyusun sumber daya serviceBus, melewati parameter existingServiceBusName.
• Menambahkan antrean bernama queue ke sumber daya serviceBus.

Tambahkan sumber daya Azure yang ada dengan string koneksi

.NET .NET Aspire menyediakan kemampuan untuk terhubung ke sumber daya yang ada, termasuk sumber daya Azure. Mengekspresikan string koneksi berguna saat Anda memiliki sumber daya Azure yang sudah ada yang ingin Anda gunakan di aplikasi .NET Aspire Anda. API AddConnectionString digunakan dengan konteks eksekusi host aplikasi untuk menambahkan string koneksi secara kondisional ke model aplikasi.

Pertimbangkan contoh berikut, di mana dalam mode publikasi Anda dapat menambahkan sumber daya Penyimpanan Azure, sementara ketika Anda berada dalam mode berjalan, Anda dapat menambahkan string koneksi ke sumber daya Penyimpanan Azure yang sudah ada.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

// After adding all resources, run the app...

Kode sebelumnya:

• Membuat instans builder baru.
• Menambahkan sumber daya Azure Storage bernama storage dalam mode "terbitkan".
• Menambahkan string koneksi pada penyimpanan Azure yang sudah ada bernama storage dalam mode "run".
• Menambahkan proyek bernama api ke builder.
• Proyek api mereferensikan sumber daya storage terlepas dari modenya.

Proyek API yang mengonsumsi informasi string koneksi tanpa mengetahui bagaimana host aplikasi mengonfigurasinya. Dalam mode "publikasi", kode menambahkan sumber daya Storage baru, yang akan tercermin dalam manifest penempatan yang sesuai. Saat dalam mode "jalankan" string koneksi sesuai dengan nilai konfigurasi yang terlihat oleh host aplikasi. Diasumsikan bahwa semua penetapan peran untuk sumber daya target telah dikonfigurasi. Ini berarti, Anda mungkin akan mengonfigurasi variabel lingkungan atau rahasia pengguna untuk menyimpan string koneksi. Konfigurasi diselesaikan dari kunci konfigurasi ConnectionStrings__storage (atau ConnectionStrings:storage). Nilai konfigurasi ini dapat dilihat saat aplikasi berjalan. Untuk informasi selengkapnya, lihat detail Sumber Daya .

Tidak seperti sumber daya yang ada yang dimodelkan dengan AsExisting API kelas satu, sumber daya yang ada yang dimodelkan sebagai string koneksi tidak dapat ditingkatkan dengan penetapan peran tambahan atau penyesuaian infrastruktur.

Terbitkan sebagai Aplikasi Kontainer Azure

.NET .NET Aspire memungkinkan Anda menerbitkan sumber daya primitif sebagai Azure Container Apps, platform tanpa server yang mengurangi manajemen infrastruktur. Jenis sumber daya yang didukung meliputi:

• ContainerResource: Mewakili kontainer tertentu.
• ExecutableResource: Mewakili proses yang dapat dieksekusi tertentu.
• ProjectResource: Mewakili proyek .NET tertentu.

Untuk menerbitkan sumber daya ini, gunakan API berikut:

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

API ini mengonfigurasi sumber daya untuk diterbitkan sebagai Aplikasi Kontainer Azure dan secara implisit memanggil AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) untuk menambahkan infrastruktur dan file Bicep yang diperlukan ke host aplikasi Anda. Sebagai contoh, pertimbangkan kode berikut:

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

Kode sebelumnya:

• Membuat instans builder baru.
• Menambahkan parameter bernama env ke builder.
• Menambahkan proyek bernama api ke builder.
• Memanggil metode PublishAsAzureContainerApp pada penyusun sumber daya api, meneruskan ekspresi lambda yang mengonfigurasi infrastruktur Aplikasi Kontainer Azure—di mana infra adalah AzureResourceInfrastructure dan app adalah ContainerApp.
  • Menambahkan variabel lingkungan bernama Hello ke aplikasi kontainer, menggunakan parameter env.
  • Metode AsProvisioningParameter digunakan untuk memperlakukan env sebagai ProvisioningParameter baru dalam infrastruktur, atau menggunakan kembali parameter bicep yang ada jika parameter dengan nama yang sama sudah ada.

Untuk informasi lebih lanjut, lihat ContainerApp dan AsProvisioningParameter.

Infrastruktur sebagai kode

SDK Azure untuk .NET menyediakan paket NuGet 📦Azure.Provisioning dan serangkaian paket penyediaan Azure yang khusus untuk layanan. Pustaka penyediaan Azure ini memudahkan untuk menentukan infrastruktur Azure secara deklaratif dan asli di .NET. API mereka memungkinkan Anda mengembangkan infrastruktur berorientasi objek di C#, yang menghasilkan Bicep. Bicep adalah bahasa khusus domain (DSL) untuk mengimplementasikan sumber daya Azure secara deklaratif.

Meskipun dimungkinkan untuk menyediakan sumber daya Azure secara manual, .NET Aspire menyederhanakan proses dengan menyediakan sekumpulan API untuk mengekspresikan sumber daya Azure. API ini tersedia sebagai metode ekstensi di pustaka hosting .NET AspireAzure, memperluas antarmuka IDistributedApplicationBuilder. Saat Anda menambahkan sumber daya Azure ke host aplikasi Anda, ini secara implisit menambahkan fungsionalitas provisi yang sesuai. Dengan kata lain, Anda tidak perlu memanggil API provisi apa pun secara langsung.

Karena model .NET Aspire memetakan sumber daya Azure dalam integrasi hosting Azure, SDK Azure digunakan untuk menyediakan sumber daya ini. File Bicep dihasilkan yang menentukan sumber daya Azure yang Anda perlukan. File Bicep yang dihasilkan dihasilkan sebagai output bersama file manifes saat Anda menerbitkan aplikasi Anda.

Ada beberapa cara untuk memengaruhi file Bicep yang dihasilkan:

• Azure.Penyesuaian pengaturan:
  • Mengonfigurasi infrastruktur: Menyesuaikan infrastruktur sumber daya Azure.
  • Tambahkan infrastruktur Azure: Tambahkan infrastruktur Azure secara manual ke host aplikasi Anda.
• Gunakan templat Bicep kustom:
  • Referensi file Bicep: Tambahkan referensi ke file Bicep di disk.
  • Referensi Bicep sebaris: Tambahkan templat Bicep sebaris.

Penyediaan Lokal dan Azure.Provisioning

Untuk menghindari istilah yang membingungkan dan membantu membedakan "provisi", penting untuk memahami perbedaan antara provisi lokal dan provisi Azure:

• Provisi lokal:

  Secara default, saat Anda memanggil salah satu API integrasi hosting Azure untuk menambahkan sumber daya Azure, API AddAzureProvisioning(IDistributedApplicationBuilder) disebut secara implisit. API ini mendaftarkan layanan dalam kontainer injeksi dependensi (DI) yang digunakan untuk menyediakan sumber daya Azure saat host aplikasi dimulai. Konsep ini dikenal sebagai penyediaan lokal. Untuk informasi selengkapnya, lihat pengaturan Azure lokal.

• Azure.Provisioning:

  Azure.Provisioning mengacu pada paket NuGet, dan merupakan sekumpulan pustaka yang memungkinkan Anda menggunakan C# untuk menghasilkan Bicep. Integrasi hosting Azure di .NET Aspire menggunakan pustaka ini secara tersembunyi untuk menghasilkan file Bicep yang menentukan sumber daya Azure Anda butuhkan. Untuk informasi selengkapnya, lihat kustomisasi Azure.Provisioning.

kustomisasi Azure.Provisioning

Semua integrasi hosting .NET AspireAzure mengekspos berbagai sumber daya Azure, dan semuanya adalah subkelas dari jenis AzureProvisioningResource — yang mewarisi AzureBicepResource. Ini memungkinkan ekstensi yang dibatasi jenis secara generik ke jenis ini, memungkinkan API yang fasih untuk menyesuaikan infrastruktur sesuai keinginan Anda. Meskipun .NET.NET Aspire menyediakan default, Anda bebas untuk memengaruhi Bicep yang dihasilkan menggunakan API ini.

Konfigurasi infrastruktur

Tidak peduli sumber daya Azure yang Anda kerjakan, untuk mengonfigurasi infrastruktur dasarnya, Anda menjalinkan panggilan ke metode ekstensi ConfigureInfrastructure. Metode ini memungkinkan Anda menyesuaikan infrastruktur sumber daya Azure dengan meneruskan delegasi jenis configureAction<AzureResourceInfrastructure>. Jenis AzureResourceInfrastructure adalah subkelas dari Azure.Provisioning.Infrastructure. Jenis ini mengekspos luas permukaan API yang besar untuk mengonfigurasi infrastruktur dasar dari sumber daya Azure.

Pertimbangkan contoh berikut:

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

Kode sebelumnya:

• Menambahkan parameter bernama storage-sku.
• Menambahkan penyimpanan Azure dengan API AddAzureStorage yang diberi nama storage.
• Menautkan panggilan ke ConfigureInfrastructure untuk menyesuaikan infrastruktur penyimpanan Azure.
  • Mendapatkan sumber daya yang dapat disediakan.
  • Memfilter menjadi satu StorageAccount.
  • Menetapkan parameter storage-sku ke properti StorageAccount.Sku:
    • Instans baru StorageSku memiliki properti Name yang ditetapkan dari hasil API AsProvisioningParameter.

Ini mencontohkan mengalirkan parameter eksternal ke infrastruktur Penyimpanan Azure, menghasilkan file Bicep yang mencerminkan konfigurasi yang diinginkan.

Tambahkan Azure infrastruktur

Tidak semua layanan Azure diekspos sebagai integrasi .NET Aspire. Meskipun mungkin di lain waktu, Anda masih dapat menyediakan layanan yang tersedia di perpustakaan Azure.Provisioning.*. Bayangkan skenario di mana Anda memiliki layanan pekerja yang bertanggung jawab untuk mengelola Azure Container Registry. Sekarang bayangkan bahwa proyek host aplikasi mengandalkan pada dependensi paket NuGet 📦Azure.Provisioning.ContainerRegistry.

Anda dapat menggunakan API AddAzureInfrastructure untuk menambahkan infrastruktur Azure Container Registry ke host aplikasi Anda:

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

Kode sebelumnya:

• Memanggil AddAzureInfrastructure dengan nama acr.
• Menyediakan delegasi configureInfrastructure untuk mengustomisasi infrastruktur Azure Container Registry.
  • Menginisialisasi ContainerRegistryService dengan nama acr dan SKU standar.
  • Menambahkan layanan Azure Container Registry ke variabel infra.
  • Menginisialisasi ProvisioningOutput dengan nama registryName, tipe string, dan nilai yang sesuai dengan nama Container Registry Azure.
  • Menambahkan output ke variabel infra.
• Menambahkan proyek bernama worker ke builder.
• Menautkan panggilan ke WithEnvironment untuk mengatur variabel lingkungan ACR_REGISTRY_NAME dalam proyek ke nilai output registryName.

Fungsionalitas menunjukkan cara menambahkan infrastruktur Azure ke proyek host aplikasi Anda, meskipun layanan Azure tidak secara langsung diekspos sebagai integrasi .NET Aspire. Ini lebih lanjut menunjukkan cara mengalirkan output Azure Container Registry ke lingkungan proyek dependen.

Pertimbangkan file Bicep yang dihasilkan:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

File Bicep mencerminkan konfigurasi yang diinginkan dari Azure Container Registry, seperti yang didefinisikan oleh API AddAzureInfrastructure.

Menggunakan templat Bicep kustom

Saat menargetkan Azure sebagai penyedia cloud yang diinginkan, Anda dapat menggunakan Bicep untuk menentukan infrastruktur Anda sebagai kode. Ini bertujuan untuk secara drastis menyederhanakan pengalaman penulisan dengan sintaks yang lebih bersih dan dukungan yang lebih baik untuk modularitas dan penggunaan kembali kode.

Meskipun .NET.NET Aspire menyediakan sekumpulan templat Bicep bawaan, mungkin ada kalanya Anda ingin menyesuaikan templat atau membuat templat Anda sendiri. Bagian ini menjelaskan konsep dan API terkait yang dapat Anda gunakan untuk menyesuaikan templat Bicep.

Sebagai bagian dari cerita penyebaran Azure untuk .NET Aspire, Azure Developer CLI (azd) memberikan pemahaman tentang proyek .NET Aspire Anda dan kemampuan untuk menyebarkannya ke Azure. CLI azd menggunakan templat Bicep untuk menyebarkan aplikasi ke Azure.

Menginstal paket Aspire.Hosting.Azure

Ketika Anda ingin mereferensikan file Bicep, ada kemungkinan Anda tidak menggunakan salah satu integrasi hosting Azure. Dalam hal ini, Anda masih dapat mereferensikan file Bicep dengan menginstal paket Aspire.Hosting.Azure. Paket ini menyediakan API yang diperlukan untuk mereferensikan file Bicep dan menyesuaikan sumber daya Azure.

Untuk menggunakan salah satu fungsi ini, 📦Aspire. Hosting.Azure paket NuGet harus diinstal:

dotnet add package Aspire.Hosting.Azure

<PackageReference Include="Aspire.Hosting.Azure"
                  Version="*" />

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Apa yang diharapkan dari contoh

Semua contoh di bagian ini mengasumsikan bahwa Anda menggunakan namespace Aspire.Hosting.Azure. Selain itu, contoh mengasumsikan Anda memiliki instans IDistributedApplicationBuilder:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Secara default, saat Anda memanggil salah satu API terkait Bicep, panggilan juga dilakukan untuk AddAzureProvisioning yang menambahkan dukungan untuk menghasilkan sumber daya Azure secara dinamis selama pengaktifan aplikasi. Untuk informasi selengkapnya, lihat Provisi lokal dan Azure.Provisioning.

Mereferensikan file Bicep

Bayangkan Anda memiliki templat Bicep dalam file bernama storage.bicep yang menyediakan Akun Penyimpanan Azure:

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Untuk menambahkan referensi ke file Bicep pada disk, panggil metode AddBicepTemplate. Pertimbangkan contoh berikut:

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

Kode sebelumnya menambahkan referensi ke file Bicep yang terletak di ../infra/storage.bicep. Jalur file harus relatif terhadap proyek app host. Referensi ini menghasilkan AzureBicepResource ditambahkan ke kumpulan sumber daya aplikasi dengan nama "storage", dan API mengembalikan instans IResourceBuilder<AzureBicepResource> yang dapat digunakan untuk menyesuaikan sumber daya lebih lanjut.

Referensi Bicep dalam garis

Meskipun memiliki file Bicep pada disk adalah skenario yang paling umum, Anda juga dapat menambahkan templat Bicep secara langsung. Templat sebaris dapat berguna saat Anda ingin menentukan templat dalam kode atau saat Anda ingin menghasilkan templat secara dinamis. Untuk menambahkan templat Bicep sebaris, panggil metode AddBicepTemplateString dengan templat Bicep sebagai string. Pertimbangkan contoh berikut:

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

Dalam contoh ini, templat Bicep didefinisikan sebagai string sebaris dan ditambahkan ke koleksi sumber daya aplikasi dengan nama "ai". Contoh ini menyediakan sumber daya AI Azure.

Meneruskan parameter ke templat Bicep

Bicep mendukung penerimaan parameter, yang dapat digunakan untuk menyesuaikan perilaku templat. Untuk meneruskan parameter ke dalam templat Bicep dari .NET.NET Aspire, lakukan pemanggilan metode WithParameter secara berantai seperti yang ditunjukkan dalam contoh berikut:

var region = builder.AddParameter("region");

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

Kode sebelumnya:

• Menambahkan parameter bernama "region" ke instans builder.
• Menambahkan referensi ke file Bicep yang terletak di ../infra/storage.bicep.
• Meneruskan parameter "region" ke templat Bicep, yang diproses menggunakan resolusi parameter standar.
• Meneruskan parameter "storageName" ke templat Bicep dengan nilai tersemat.
• Meneruskan parameter "tags" ke templat Bicep dengan array string.

Untuk informasi selengkapnya, lihat Parameter eksternal.

Parameter terkenal

.NET .NET Aspire menyediakan sekumpulan parameter terkenal yang dapat diteruskan ke templat Bicep. Parameter ini digunakan untuk memberikan informasi tentang aplikasi dan lingkungan ke templat Bicep. Parameter terkenal berikut ini tersedia:

Untuk menggunakan parameter terkenal, teruskan nama parameter ke metode WithParameter, seperti WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Anda tidak meneruskan nilai untuk parameter yang sudah dikenal, karena .NET.NET Aspire menanganinya untuk Anda.

Pertimbangkan sebuah contoh di mana Anda ingin menyiapkan Event Grid webhook Azure. Anda dapat menentukan templat Bicep sebagai berikut:

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

Templat Bicep ini mendefinisikan beberapa parameter, termasuk topicName, webHookEndpoint, principalId, principalType, dan locationopsional . Untuk meneruskan parameter ini ke templat Bicep, Anda dapat menggunakan cuplikan kode berikut:

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);

• Proyek webHookApi ditambahkan sebagai referensi ke builder.
• Parameter topicName diberikan nilai nama yang sudah di-hardcode.
• Parameter webHookEndpoint diteruskan sebagai ekspresi yang mengarah ke URL dari endpoint "https" rujukan proyek api melalui rute /hook.
• Parameter principalId dan principalType diteruskan sebagai parameter yang dikenal umum.

Parameter terkenal berbasis konvensi dan tidak boleh disertai dengan nilai yang sesuai saat diteruskan menggunakan API WithParameter. Parameter yang umum dikenal menyederhanakan beberapa fungsi umum, seperti penetapan peran, saat ditambahkan ke templat Bicep, seperti yang ditunjukkan sebelumnya. Penetapan peran diperlukan agar webhook Event Grid mengirim peristiwa ke titik akhir yang ditentukan. Untuk informasi selengkapnya, lihat penetapan peran Pengirim Data Event Grid.

Dapatkan keluaran dari referensi Bicep

Selain meneruskan parameter ke templat Bicep, Anda juga bisa mendapatkan output dari templat Bicep. Pertimbangkan templat Bicep berikut, karena mendefinisikan output bernama endpoint:

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Bicep mendefinisikan sebuah output bernama endpoint. Untuk mendapatkan output dari templat Bicep, panggil metode GetOutput pada instans IResourceBuilder<AzureBicepResource> seperti yang ditunjukkan dalam cuplikan kode C# berikut:

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

Dalam contoh ini, output dari templat Bicep diambil dan disimpan dalam variabel endpoint. Biasanya, Anda akan meneruskan output ini sebagai variabel lingkungan ke sumber daya lain yang bergantung padanya. Misalnya, jika Anda memiliki proyek API Minimal ASP.NET Core yang bergantung pada titik akhir ini, Anda dapat meneruskan output sebagai variabel lingkungan ke proyek menggunakan cuplikan kode berikut:

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

Untuk informasi selengkapnya, lihat keluaran Bicep.

Dapatkan output rahasia dari referensi Bicep

Penting untuk menghindari pengeluaran rahasia saat bekerja dengan Bicep. Jika output dianggap sebagai rahasia, yang berarti tidak boleh diekspos di log atau tempat lain, perlakukan saja demikian. Ini dapat dicapai dengan menyimpan rahasia dalam Azure Key Vault dan mereferensikannya dalam templat Bicep. integrasi .NET AspireAzuremenyediakan pola untuk penyimpanan output yang aman dari templat Bicep dengan memungkinkan sumber daya untuk menggunakan parameter keyVaultName untuk menyimpan rahasia di Azure Key Vault.

Pertimbangkan templat Bicep berikut sebagai contoh yang membantu menunjukkan konsep mengamankan output rahasia ini:

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

Templat Bicep sebelumnya mengharapkan parameter keyVaultName, di antara beberapa parameter lainnya. Kemudian mendefinisikan sumber daya Azure Cosmos DB dan menyimpan kunci rahasia ke dalam Azure Key Vault, bernama connectionString yang mewakili string koneksi yang memenuhi syarat sepenuhnya ke instans Cosmos DB. Untuk mengakses nilai string koneksi rahasia ini, Anda dapat menggunakan cuplikan kode berikut:

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

Dalam cuplikan kode sebelumnya, templat bicep cosmos ditambahkan sebagai referensi ke builder. Keluaran rahasia connectionString diperoleh dari template Bicep dan disimpan dalam variabel. Output rahasia kemudian diteruskan sebagai variabel lingkungan (ConnectionStrings__cosmos) ke proyek api. Variabel lingkungan ini digunakan untuk terhubung ke instans Cosmos DB.

Ketika sumber daya ini disebarkan, mekanisme penyebaran yang mendasar akan secara otomatis mengacu pada rahasia dari Azure Key Vault. Untuk menjamin isolasi rahasia, .NET.NET Aspire membuat Key Vault per sumber.

Penerbitan

Saat Anda memublikasikan aplikasi, provisi Azure yang dihasilkan Bicep digunakan oleh Azure Developer CLI untuk membuat sumber daya Azure di langganan Azure Anda. .NET .NET Aspire menghasilkan manifes penerbitan , yang juga merupakan bagian penting dari proses penerbitan. Azure Developer CLI adalah alat baris perintah yang menyediakan sekumpulan perintah untuk mengelola sumber daya Azure.

Untuk informasi selengkapnya tentang penerbitan dan penyebaran, lihat Menyebarkan proyek .NET Aspire untuk Azure Container Apps menggunakan Azure Developer CLI (panduan mendalam).