Bagikan melalui

gambaran umum orkestrasi .NET.NET Aspire

.NET .NET Aspire menyediakan API untuk mengekspresikan sumber daya dan dependensi dalam aplikasi terdistribusi Anda. Selain API ini, ada alat yang memungkinkan beberapa skenario menarik. Orkestrator ditujukan untuk pengembangan lokal dan tidak didukung di lingkungan produksi.

Sebelum melanjutkan, pertimbangkan beberapa terminologi umum yang digunakan dalam .NET.NET Aspire:

  • Model aplikasi: Kumpulan sumber daya yang membentuk aplikasi terdistribusi Anda (DistributedApplication), yang ditentukan dalam Aspire.Hosting.ApplicationModel namespace. Untuk definisi yang lebih formal, lihat Menentukan model aplikasi.
  • Proyek host aplikasi/Orkestrator: Proyek .NET yang mengorkestrasi model aplikasi, dinamai dengan akhiran *.AppHost (menurut konvensi).
  • Sumber daya: Sumber daya adalah bagian dependen dari aplikasi, seperti .NET proyek, kontainer, executable, database, cache, atau layanan cloud. Ini mewakili bagian mana pun dari aplikasi yang dapat dikelola atau dirujuk.
  • Integrasi: Integrasi adalah paket NuGet untuk host aplikasi yang memodelkan sumber daya atau paket yang mengonfigurasi klien untuk digunakan dalam aplikasi konsumen. Untuk informasi selengkapnya, lihat .NET.NET Aspire gambaran umum integrasi.
  • Referensi: Referensi mendefinisikan koneksi antara sumber daya, yang dinyatakan sebagai dependensi menggunakan WithReference API. Untuk informasi selengkapnya, lihat Referensi sumber daya atau Referensi sumber daya yang ada.

Nota

.NET .NET AspireOrkestrasi ini dirancang untuk meningkatkan pengalaman pengembangan lokal Anda dengan menyederhanakan pengelolaan konfigurasi dan interkoneksi aplikasi cloud-native Anda. Meskipun ini adalah alat yang sangat berharga untuk pengembangan, ini tidak dimaksudkan untuk mengganti sistem lingkungan produksi seperti Kubernetes, yang dirancang khusus untuk unggul dalam konteks tersebut.

Menentukan model aplikasi

.NET .NET Aspire memungkinkan Anda membangun, menyediakan, menyebarkan, mengonfigurasi, menguji, menjalankan, dan memantau aplikasi terdistribusi anda secara efisien. Kemampuan ini didukung oleh model aplikasi, yang menentukan sumber daya dalam solusi Anda .NET.NET Aspire dan interkoneksinya.

Model aplikasi lebih dari sekadar daftar sumber daya—ini mewakili topologi lengkap aplikasi Anda. Ini termasuk hubungan antara sumber daya, dependensinya, dan konfigurasinya. Sumber daya dapat mencakup proyek, executable, kontainer, layanan eksternal, dan sumber daya cloud yang diandalkan aplikasi Anda.

.NET .NET Aspire Di proyek host aplikasi, file Anda Program menentukan model aplikasi Anda:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Saat memanggil DistributedApplication.CreateBuilder, Anda mendapatkan instans IDistributedApplicationBuilder, yang digunakan untuk mengonfigurasi model aplikasi Anda. Penyusun ini menyediakan metode untuk menambahkan sumber daya, menentukan dependensi, dan menyiapkan struktur keseluruhan aplikasi Anda. Setelah Anda menambahkan sumber daya, panggil Build untuk membuat model aplikasi. Template mencakup kode yang menautkan panggilan ke Build()—yang mengembalikan instans DistributedApplication, lalu memanggil Run().

Proyek host aplikasi

Proyek host aplikasi menangani menjalankan semua proyek yang merupakan bagian dari proyek .NET.NET Aspire. Dengan kata lain, ia bertanggung jawab untuk mengatur semua aplikasi dalam model aplikasi. Proyek itu sendiri adalah proyek .NET yang dapat dieksekusi yang merujuk pada 📦Aspire.Hosting.AppHost paket NuGet, dan menggunakan .NET.NET Aspire SDK:

<Project Sdk="Microsoft.NET.Sdk">

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net9.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
    </ItemGroup>

    <!-- Omitted for brevity -->

</Project>

Kode berikut menjelaskan aplikasi host Program dengan referensi dua proyek dan cache Redis.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WaitFor(cache)
       .WithReference(apiService)
       .WaitFor(apiService);

builder.Build().Run();

Kode sebelumnya:

  • Membuat pembuat model aplikasi baru menggunakan metode CreateBuilder.
  • Menambahkan sumber daya Rediscache bernama "cache" menggunakan metode AddRedis.
  • Menambahkan sumber daya proyek bernama "apiservice" menggunakan metode AddProject.
  • Menambahkan sumber daya proyek bernama "webfrontend" menggunakan metode AddProject.
    • Menentukan bahwa proyek memiliki titik akhir HTTP eksternal menggunakan metode WithExternalHttpEndpoints.
    • Menambahkan referensi ke sumber daya cache dan menunggunya siap menggunakan metode WithReference dan WaitFor.
    • Menambahkan referensi ke sumber daya apiservice dan menunggunya siap menggunakan metode WithReference dan WaitFor.
  • Membangun dan menjalankan model aplikasi menggunakan metode Build dan Run.

Contoh kode menggunakan .NET AspireRedis integrasi hosting.

Untuk membantu memvisualisasikan hubungan antara proyek host aplikasi dan sumber daya yang dijelaskannya, pertimbangkan diagram berikut:

Hubungan antara proyek dalam templat Aplikasi Pemula .NET.NET Aspire .

Setiap sumber daya harus diberi nama unik. Diagram ini memperlihatkan setiap sumber daya dan hubungan di antaranya. Sumber daya kontainer diberi nama "cache" dan sumber daya proyek diberi nama "apiservice" dan "webfrontend". Proyek frontend web mereferensikan cache dan proyek layanan API. Saat Anda mengekspresikan referensi dengan cara ini, proyek frontend web mengatakan bahwa itu tergantung pada kedua sumber daya ini, masing-masing "cache" dan "apiservice".

Jenis sumber daya bawaan

.NET .NET Aspire proyek terdiri dari sekumpulan sumber daya. Jenis sumber daya dasar utama di 📦Aspire. Paket Hosting.AppHost NuGet dijelaskan dalam tabel berikut:

Metode Jenis sumber daya Deskripsi
AddProject ProjectResource Proyek .NET, misalnya, aplikasi web ASP.NET Core.
AddContainer ContainerResource Gambar kontainer, seperti gambar Docker.
AddExecutable ExecutableResource File yang dapat dieksekusi, seperti Node.js aplikasi.
AddParameter ParameterResource Sumber daya parameter yang dapat digunakan untuk mengekspresikan parameter eksternal.

Sumber daya proyek mewakili proyek .NET yang merupakan bagian dari model aplikasi. Saat Anda menambahkan referensi proyek ke proyek host aplikasi, .NET.NET Aspire SDK menghasilkan jenis di namespace Projects untuk setiap proyek yang dirujuk. Untuk informasi selengkapnya, lihat .NET.NET Aspire SDK: Referensi proyek.

Untuk menambahkan proyek ke model aplikasi, gunakan metode AddProject:

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

Proyek dapat direplikasi dan diskalakan dengan menambahkan beberapa instans proyek yang sama ke model aplikasi. Untuk mengonfigurasi replika, gunakan metode WithReplicas:

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReplicas(3);

Kode sebelumnya menambahkan tiga replika sumber daya proyek "apiservice" ke model aplikasi. Untuk informasi selengkapnya, lihat .NET.NET Aspire dasbor: Replika sumber daya.

Sumber daya referensi

Referensi mewakili dependensi antara sumber daya. Misalnya, Anda mungkin dapat membayangkan skenario di mana frontend web bergantung pada Redis cache. Pertimbangkan contoh kode C# aplikasi host Program berikut:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache);

Sumber daya proyek "webfrontend" menggunakan WithReference untuk menambahkan dependensi pada sumber daya kontainer "cache". Dependensi ini dapat mewakili string koneksi atau informasi penemuan layanan . Dalam contoh sebelumnya, variabel lingkungan disuntikkan ke sumber daya "webfrontend" dengan nama ConnectionStrings__cache. Variabel lingkungan ini berisi string koneksi yang webfrontend menggunakan untuk terhubung Redis melalui .NET AspireRedis integrasi, misalnya, ConnectionStrings__cache="localhost:62354".

String koneksi dan referensi titik akhir

Umum untuk mengekspresikan dependensi antara sumber daya proyek. Pertimbangkan contoh kode berikut:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache)
       .WithReference(apiservice);

Referensi proyek-ke-proyek ditangani secara berbeda dari sumber daya yang memiliki string koneksi yang terdefinisi dengan baik. Alih-alih string koneksi disuntikkan ke sumber daya "webfrontend", variabel lingkungan untuk mendukung penemuan layanan disuntikkan.

Metode Variabel lingkungan
WithReference(cache) ConnectionStrings__cache="localhost:62354"
WithReference(apiservice) services__apiservice__http__0="http://localhost:5455"
services__apiservice__https__0="https://localhost:7356"

Menambahkan referensi ke proyek "apiservice" menghasilkan variabel lingkungan penemuan layanan yang ditambahkan ke frontend. Ini karena biasanya, komunikasi proyek-ke-proyek terjadi melalui HTTP/gRPC. Untuk informasi selengkapnya, lihat .NET.NET Aspire penemuan layanan.

Untuk mendapatkan titik akhir tertentu dari ContainerResource atau ExecutableResource, gunakan salah satu API titik akhir berikut:

Kemudian panggil API GetEndpoint untuk mendapatkan titik akhir yang dapat digunakan untuk mereferensikan titik akhir dalam metode WithReference:

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
                             .WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReference(endpoint);
Metode Variabel lingkungan
WithReference(endpoint) services__myapp__endpoint__0=https://localhost:9043

Parameter port adalah port yang digunakan oleh kontainer untuk mendengarkan. Untuk informasi selengkapnya tentang port kontainer, lihat Port kontainer. Untuk informasi selengkapnya tentang penemuan layanan, lihat .NET.NET Aspire penemuan layanan.

Format variabel lingkungan titik akhir layanan

Di bagian sebelumnya, metode WithReference digunakan untuk mengekspresikan dependensi antar sumber daya. Ketika titik akhir layanan mengakibatkan variabel lingkungan disuntikkan ke dalam sumber daya dependen, formatnya mungkin tidak jelas. Bagian ini menyediakan detail tentang format ini.

Ketika satu sumber daya bergantung pada sumber daya lain, host aplikasi menyuntikkan variabel lingkungan ke dalam sumber daya dependen. Variabel lingkungan ini mengonfigurasi sumber daya dependen untuk terhubung ke sumber daya yang bergantung padanya. Format variabel lingkungan khusus untuk .NET.NET Aspire dan mengekspresikan titik akhir layanan dengan cara yang kompatibel dengan Penemuan Layanan.

Nama variabel lingkungan titik akhir layanan diawali dengan services__ (garis bawah ganda), lalu nama layanan, nama titik akhir, dan akhirnya indeks. Indeks mendukung beberapa titik akhir untuk satu layanan, dimulai dengan 0 untuk titik akhir pertama dan bertahap untuk setiap titik akhir.

Pertimbangkan contoh variabel lingkungan berikut:

services__apiservice__http__0

Variabel lingkungan sebelumnya mengekspresikan titik akhir HTTP pertama untuk layanan apiservice. Nilai variabel lingkungan adalah URL titik akhir layanan. Titik akhir bernama mungkin dinyatakan sebagai berikut:

services__apiservice__myendpoint__0

Dalam contoh sebelumnya, layanan apiservice memiliki titik akhir bernama yang disebut myendpoint. Nilai variabel lingkungan adalah URL titik akhir layanan.

Mereferensikan sumber daya yang ada

Dalam beberapa situasi, Anda perlu merujuk pada sumber daya yang ada, mungkin yang telah diterapkan pada penyedia cloud. Misalnya, Anda mungkin ingin mereferensikan database Azure. Dalam hal ini, Anda akan mengandalkan konteks eksekusi untuk menentukan secara dinamis apakah host aplikasi berjalan dalam mode "jalankan" atau mode "terbitkan". Jika Anda menjalankan secara lokal dan ingin mengandalkan sumber daya cloud, Anda dapat menggunakan properti IsRunMode untuk menambahkan referensi secara kondisional. Anda dapat memilih untuk membuat sumber daya dalam mode publikasi. Beberapa integrasi hosting mendukung penyediaan string koneksi secara langsung, yang dapat digunakan untuk mereferensikan sumber daya yang ada.

Demikian juga, mungkin ada kasus penggunaan di mana Anda ingin mengintegrasikan .NET.NET Aspire ke dalam solusi yang ada. Salah satu pendekatan umum adalah menambahkan proyek host aplikasi .NET.NET Aspire ke solusi yang ada. Dalam host aplikasi, Anda mengekspresikan dependensi dengan menambahkan referensi proyek ke host aplikasi dan membangun model aplikasi. Misalnya, satu proyek mungkin bergantung pada proyek lain. Dependensi ini dinyatakan menggunakan metode WithReference. Untuk informasi selengkapnya, lihat Menambahkan .NET Aspire ke aplikasi yang sudah ada.NET.

Konteks eksekusi

IDistributedApplicationBuilder mengekspos konteks eksekusi (DistributedApplicationExecutionContext), yang menyediakan informasi tentang eksekusi host aplikasi saat ini. Konteks ini dapat digunakan untuk mengevaluasi apakah host aplikasi sedang dieksekusi sebagai mode "jalankan" atau tidak, atau sebagai bagian dari operasi penerbitan. Pertimbangkan properti berikut:

  • IsRunMode: Mengembalikan true jika operasi saat ini sedang berjalan.
  • IsPublishMode: Mengembalikan true jika operasi saat ini sedang dalam proses publikasi.

Informasi ini dapat berguna ketika Anda ingin menjalankan kode secara kondisional berdasarkan operasi saat ini. Pertimbangkan contoh berikut yang menunjukkan penggunaan properti IsRunMode. Dalam hal ini, metode ekstensi digunakan untuk menghasilkan nama simpul yang stabil untuk RabbitMQ untuk eksekusi pengembangan lokal.

private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
    this IResourceBuilder<RabbitMQServerResource> builder)
{
    if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
    {
        builder.WithEnvironment(context =>
        {
            // Set a stable node name so queue storage is consistent between sessions
            var nodeName = $"{builder.Resource.Name}@localhost";
            context.EnvironmentVariables["RABBITMQ_NODENAME"] = nodeName;
        });
    }

    return builder;
}

Konteks eksekusi sering digunakan untuk menambahkan sumber daya atau string koneksi secara kondisional yang menunjuk ke sumber daya yang ada. Pertimbangkan contoh berikut yang menunjukkan penambahan Redis atau string koneksi secara kondisional berdasarkan konteks eksekusi:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.ExecutionContext.IsRunMode
    ? builder.AddRedis("redis")
    : builder.AddConnectionString("redis");

builder.AddProject<Projects.WebApplication>("api")
       .WithReference(redis);

builder.Build().Run();

Dalam kode sebelumnya:

  • Jika host aplikasi dalam mode "run", sumber daya kontainer Redis ditambahkan.
  • Jika host aplikasi dalam mode "terbitkan", string koneksi ditambahkan.

Logika ini dapat dengan mudah dibalikkan untuk terhubung ke sumber daya Redis yang ada saat Anda menjalankan tugas secara lokal, dan membuat sumber daya Redis baru saat Anda melakukan publikasi.

Penting

.NET .NET Aspire menyediakan API umum untuk mengontrol modalitas pembangun sumber daya, memungkinkan sumber daya berperilaku berbeda berdasarkan mode eksekusi. API fluida dimulai dengan RunAs* dan PublishAs*. API RunAs* memengaruhi perilaku pengembangan lokal (atau mode eksekusi), sedangkan API PublishAs* memengaruhi penerbitan sumber daya. Untuk informasi selengkapnya tentang cara Azure sumber daya menggunakan API ini, lihat Menggunakan sumber daya yang Azure ada.

Lihat juga