Mulai cepat: Membangun solusi .NET.NET Aspire pertama Anda

2024-12-14

Aplikasi cloud-native sering memerlukan koneksi ke berbagai layanan seperti database, solusi penyimpanan dan caching, penyedia pesan, atau layanan web lainnya. .NET .NET Aspire dirancang untuk menyederhanakan koneksi dan konfigurasi antara jenis layanan ini. Panduan cepat ini menunjukkan cara membuat solusi templat Aplikasi Starter .NET.NET Aspire.

Dalam panduan cepat ini, Anda mempelajari tugas berikut:

Buat aplikasi .NET dasar yang telah disiapkan untuk menggunakan .NET Aspire.
Tambahkan dan konfigurasikan integrasi .NET.NET Aspire untuk menerapkan caching saat pembuatan proyek.
Buat API dan gunakan penemuan layanan untuk menyambungkannya.
Mengatur komunikasi antara UI front end, API back end, dan cache Redis lokal.

Prasyarat

Untuk bekerja dengan .NET.NET Aspire, Anda memerlukan hal berikut yang diinstal secara lokal:

.NET 8.0 atau .NET 9.0
Waktu jalan kontainer yang sesuai dengan OCI, seperti:
- Docker Desktop atau Podman. Untuk informasi selengkapnya, lihat kontainer runtime.
Lingkungan Pengembang Terintegrasi (IDE) atau editor kode, seperti:
- Visual Studio 2022 versi 17.9 atau lebih tinggi (Opsional)
- Visual Studio Code (Opsional)
  - C# Dev Kit: Ekstensi (Opsional)
- JetBrains Rider dengan .NET.NET Aspire plugin (opsional)

Untuk informasi selengkapnya, lihat penyiapan dan alat .NET.NET Aspire, dan .NET.NET Aspire SDK.

Membuat templat .NET.NET Aspire

Untuk membuat Aplikasi Pemula .NET Aspire baru, Anda dapat menggunakan Visual Studio, Visual Studio Code, atau CLI .NET.

Visual Studio menyediakan templat .NET Aspire yang menangani beberapa konfigurasi penyiapan awal untuk Anda. Selesaikan langkah-langkah berikut untuk membuat proyek untuk panduan memulai cepat ini.

Di bagian atas Visual Studio, navigasikan ke File >Proyek>Baru.
Di jendela dialog, cari Aspire dan pilih .NET.NET Aspire Starter App. Pilih Berikutnya.
Di layar Konfigurasikan proyek baru Anda:
- Masukkan Nama Proyek dari AspireSample.
- Biarkan nilai lainnya di defaultnya dan pilih Berikutnya.
Pada layar informasi tambahan:
- Pastikan .NET 9.0 (Dukungan Istilah Standar) dipilih.
- Pastikan bahwa Gunakan Redis untuk cache (memerlukan runtime kontainer yang didukung) sudah dicentang dan pilih Buat.
- Secara opsional, Anda dapat memilih Membuat proyek pengujian. Untuk informasi selengkapnya, lihat Tulis uji coba .NET.NET Aspire pertama Anda.

Visual Studio membuat solusi baru yang disusun untuk menggunakan .NET Aspire.

Visual Studio Code menyediakan templat proyek .NET Aspire yang menangani beberapa konfigurasi penyiapan awal untuk Anda. Selesaikan langkah-langkah berikut untuk membuat proyek untuk panduan memulai cepat ini.

Dari instans baru Visual Studio Code (tanpa folder terbuka), pilih tombol Buat proyek .NET.
Pilih templat .NET.NET Aspire Aplikasi Pemula.
Pilih folder untuk proyek baru, dan masukkan nama untuk proyek tersebut.

Jika Anda belum menginstal templat .NET.NET Aspire, jalankan perintah dotnet new install berikut:

dotnet new install Aspire.ProjectTemplates

Perintah CLI .NET sebelumnya memastikan bahwa Anda memiliki templat .NET Aspire yang tersedia. Untuk membuat Aplikasi Pemula .NET.NET Aspire dari templat, jalankan perintah dotnet new berikut:

dotnet new aspire-starter --use-redis-cache --output AspireSample

Untuk informasi selengkapnya, lihat dotnet new. CLI .NET membuat solusi baru yang terstruktur untuk menggunakan .NET Aspire.

Untuk informasi selengkapnya tentang templat yang tersedia, lihat templat .NET.NET Aspire.

Menguji aplikasi secara lokal

Aplikasi sampel mencakup aplikasi Blazor frontend yang berkomunikasi dengan proyek API Minimal. Proyek API digunakan untuk menyediakan data cuaca palsu ke frontend. Aplikasi frontend dikonfigurasi untuk menggunakan penemuan layanan untuk terhubung ke proyek API. Proyek API telah dikonfigurasi untuk menggunakan caching output dengan Redis. Aplikasi sampel sekarang siap untuk pengujian. Anda ingin memverifikasi kondisi berikut:

Data cuaca diambil dari proyek API menggunakan penemuan layanan dan ditampilkan di halaman cuaca.
Permintaan selanjutnya ditangani melalui penyimpanan sementara output yang dikonfigurasi oleh integrasi .NET AspireRedis.

Pada Visual Studio, atur proyek AspireSample.AppHost sebagai proyek startup dengan mengklik kanan pada proyek di Penjelajah Solusi dan memilih Atur sebagai Proyek Startup. Ini mungkin sudah ditetapkan secara otomatis sebagai proyek startup. Setelah diatur, tekan F5 atau (Ctrl + F5 untuk berjalan tanpa penelusuran kesalahan) untuk menjalankan aplikasi.

Anda perlu mempercayai sertifikat ASP.NET Corelocalhost sebelum menjalankan aplikasi. Jalankan perintah berikut:

dotnet dev-certs https --trust

Untuk informasi selengkapnya, lihat Memecahkan masalah sertifikat localhost yang tidak tepercaya di .NET Aspire. Untuk detail mendalam tentang pemecahan masalah sertifikat localhost pada Linux, lihat ASP.NET Core: GitHub masalah repositori #32842.

Di , tekan F5 untuk meluncurkan aplikasi. Anda diminta untuk memilih bahasa mana, dan C# disarankan. Pilih C# kemudian pilih proyek AspireSample.AppHost dengan Konfigurasi Default:

Jika ini pertama kalinya Anda menjalankan .NET Aspire, atau ini adalah komputer baru dengan penginstalan .NET baru, Anda diminta untuk menginstal sertifikat localhost yang ditandatangani sendiri—dan proyek akan gagal diluncurkan:

Pilih Ya, dan Anda melihat pesan informasi yang menunjukkan bahwa sertifikat yang ditandatangani sendiri berhasil dibuat:

Jika Anda masih mengalami masalah, tutup semua jendela browser dan coba lagi. Untuk informasi selengkapnya, lihat Memecahkan masalah sertifikat localhost yang tidak tepercaya di .NET Aspire.

Saran

Jika Anda berada di MacOS dan menggunakan Safari, saat browser terbuka jika halaman kosong, Anda mungkin perlu me-refresh halaman secara manual.

dotnet run --project AspireSample/AspireSample.AppHost

Untuk informasi selengkapnya, lihat dotnet run.

Aplikasi ini menampilkan dasbor .NET.NET Aspire di browser. Anda akan melihat dasbor lebih rinci nanti. Untuk saat ini, temukan proyek webfrontend dalam daftar sumber daya dan pilih titik akhir proyek localhost.

Beranda aplikasi webfrontend menampilkan "Halo, dunia!"
Navigasikan dari halaman beranda ke halaman cuaca di menggunakan navigasi sisi kiri. Halaman cuaca menampilkan data cuaca. Buat catatan mental dari beberapa nilai yang diwakili dalam tabel prakiraan.
Lanjutkan sesekali me-refresh halaman selama 10 detik. Dalam waktu 10 detik, data yang di-cache dikembalikan. Akhirnya, kumpulan data cuaca yang berbeda muncul, karena data dibuat secara acak dan cache diperbarui.

🤓 Selamat! Anda membuat dan menjalankan solusi .NET.NET Aspire pertama Anda! Untuk menghentikan aplikasi, tutup jendela browser.

Untuk menghentikan aplikasi di Visual Studio, pilih Hentikan Debugging dari menu Debug.

Untuk menghentikan aplikasi di , tekan ShiftF5, atau pilih tombol Berhenti di tengah atas jendela:

Untuk menghentikan aplikasi, tekan Ctrl + C di jendela terminal.

Selanjutnya, selidiki struktur dan fitur lain dari solusi .NET.NET Aspire baru Anda.

Menjelajahi dasbor .NET.NET Aspire

Saat Anda menjalankan proyek .NET.NET Aspire, dasbor diluncurkan yang Anda gunakan untuk memantau berbagai bagian aplikasi Anda. Dasbor menyerupai cuplikan layar berikut:

Kunjungi setiap halaman menggunakan navigasi kiri untuk melihat informasi berbeda tentang sumber daya .NET.NET Aspire:

Resource: Mencantumkan informasi dasar untuk semua proyek .NET individu dalam proyek .NET Aspire Anda, seperti status aplikasi, alamat titik akhir, dan variabel lingkungan yang dimuat.
Console: Menampilkan output konsol dari setiap proyek di aplikasi Anda.
Terstruktur : Menampilkan log terstruktur dalam format tabel. Log ini juga mendukung pemfilteran dasar, pencarian bentuk bebas, dan pemfilteran tingkat log. Anda akan melihat log dari apiservice dan webfrontend. Anda dapat memperluas detail setiap entri log dengan memilih tombol Tampilkan di ujung kanan baris.
Pelacakan: Menampilkan pelacakan untuk aplikasi Anda, yang dapat melacak lintasan permintaan dalam aplikasi Anda. Temukan permintaan untuk /weather dan pilih Lihat di sisi kanan halaman. Dasbor harus menampilkan permintaan secara bertahap saat berjalan melalui berbagai bagian aplikasi Anda.
Metrik: Menampilkan berbagai instrumen dan pengukur yang terlihat dan dimensi yang terkait untuk aplikasi Anda. Metrik memperlihatkan filter secara bersyarat berdasarkan dimensi yang tersedia.

Untuk informasi selengkapnya, lihat gambaran umum dasbor .NET.NET Aspire.

Memahami struktur solusi .NET.NET Aspire

Solusinya terdiri dari proyek-proyek berikut:

AspireSample.ApiService: Proyek ASP.NET Core Minimal API digunakan untuk menyediakan data ke front-end. Proyek ini tergantung pada proyek bersama AspireSample.ServiceDefaults.
AspireSample.AppHost: Proyek orkestrator yang dirancang untuk menyambungkan dan mengonfigurasi berbagai proyek dan layanan aplikasi Anda. Orkestrator harus ditetapkan sebagai proyek Startup , dan bergantung pada proyek AspireSample.ApiService dan proyek AspireSample.Web.
AspireSample.ServiceDefaults: Proyek bersama .NET.NET Aspire untuk mengelola konfigurasi yang digunakan kembali di seluruh proyek dalam solusi Anda yang terkait dengan ketahanan , penemuan layanan , dan telemetri .
AspireSample.Web: Proyek Aplikasi ASP.NET CoreBlazor dengan konfigurasi layanan .NET Aspire default, proyek ini bergantung pada proyek AspireSample.ServiceDefaults. Untuk informasi selengkapnya, lihat default layanan .NET.NET Aspire.

Direktori AspireSample Anda harus menyerupai struktur berikut:

└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Menjelajahi proyek perdana

Setiap proyek dalam solusi .NET.NET Aspire memainkan peran dalam komposisi aplikasi Anda. Proyek *.Web adalah Aplikasi ASP.NET CoreBlazor standar yang menyediakan antarmuka pengguna front end. Untuk informasi selengkapnya, lihat Apa yang baru di ASP.NET Core 9.0: Blazor. *.ApiService adalah proyek templat API Minimal ASP.NET Core standar. Kedua proyek ini bergantung pada *. ServiceDefaults proyek, yang merupakan proyek bersama yang digunakan untuk mengelola konfigurasi yang digunakan kembali di seluruh proyek dalam solusi Anda.

Dalam panduan memulai cepat ini, dua proyek yang menarik adalah *.AppHost dan *.ServiceDefaults yang dirinci di bagian berikut.

.NET .NET Aspire proyek tuan rumah

*Proyek AppHost bertanggung jawab untuk bertindak sebagai pengatur/dev-orchestrator lokal:

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

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>2aa31fdb-0078-4b71-b953-d23432af8a36</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSample.ApiService\AspireSample.ApiService.csproj" />
    <ProjectReference Include="..\AspireSample.Web\AspireSample.Web.csproj" />
  </ItemGroup>

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

</Project>

Untuk informasi selengkapnya, lihat gambaran umum orkestrasi .NET.NET Aspire dan .NET.NET Aspire SDK.

Perhatikan file proyek Program.cs dari proyek AspireSample.AppHost:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

builder.Build().Run();

Jika Anda telah menggunakan Host Generik .NET atau Web Host ASP.NET Core sebelumnya, model pemrograman dan pola penyusun host aplikasi akan terasa familiar bagi Anda. Kode sebelumnya:

Membuat instans IDistributedApplicationBuilder dengan memanggil DistributedApplication.CreateBuilder().
Panggilan AddRedis dengan nama "cache" untuk menambahkan server Redis ke aplikasi, menetapkan nilai yang dikembalikan ke variabel bernama cache, yang berjenis IResourceBuilder<RedisResource>.
Memanggil AddProject dengan parameter tipe generik yang mencakup detail proyek, serta menambahkan proyek AspireSample.ApiService ke dalam model aplikasi. Ini adalah salah satu blok penyusun dasar .NET.NET Aspire, dan digunakan untuk mengonfigurasi penemuan layanan dan komunikasi antara proyek di aplikasi Anda. Argumen nama "apiservice" digunakan untuk mengidentifikasi proyek dalam model aplikasi, dan digunakan nanti oleh proyek yang ingin berkomunikasi dengannya.
Memanggil AddProject lagi, kali ini menambahkan proyek AspireSample.Web ke model aplikasi. Ini juga menautkan beberapa panggilan ke WithReference melewati variabel cache dan apiService. API WithReference adalah API dasar lain dari .NET.NET Aspire, yang menyuntikkan informasi penemuan layanan atau konfigurasi string koneksi ke dalam proyek yang ditambahkan ke model aplikasi. Selain itu, panggilan ke API WaitFor digunakan untuk memastikan bahwa sumber daya cache dan apiService tersedia sebelum proyek AspireSample.Web dimulai. Untuk informasi lebih lanjut, lihat orkestrasi .NET.NET Aspire: Menunggu sumber daya.

Terakhir, aplikasi dibuat dan dijalankan. Metode DistributedApplication.Run() bertanggung jawab untuk memulai aplikasi dan semua dependensinya. Untuk informasi selengkapnya, lihat gambaran umum orkestrasi .NET.NET Aspire.

Saran

Panggilan ke AddRedis membuat kontainer Redis lokal untuk digunakan aplikasi. Jika Anda lebih suka hanya menunjuk ke instans Redis yang ada, Anda dapat menggunakan metode AddConnectionString untuk mereferensikan string koneksi yang ada. Untuk informasi selengkapnya, lihat referensi sumber daya yang ada.

.NET .NET Aspire layanan default proyek

*. ServiceDefaults project adalah proyek bersama yang digunakan untuk mengelola konfigurasi yang digunakan kembali di seluruh proyek dalam solusi Anda. Proyek ini memastikan bahwa semua layanan dependen memiliki ketahanan, penemuan layanan, dan konfigurasi OpenTelemetry yang sama. File proyek .NET.NET Aspire bersama berisi properti IsAspireSharedProject yang ditetapkan sebagai true:

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

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.6.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.3.1" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
  </ItemGroup>

</Project>

Proyek default layanan mengekspos metode ekstensi pada tipe IHostApplicationBuilder, bernama AddServiceDefaults. Proyek standar layanan dari template adalah titik awal, dan Anda dapat menyesuaikannya untuk memenuhi kebutuhan Anda. Untuk informasi selengkapnya, lihat default layanan .NET.NET Aspire.

Mengatur komunikasi layanan

.NET .NET Aspire menyediakan fitur orkestrasi untuk membantu mengonfigurasi koneksi dan komunikasi antara berbagai bagian aplikasi Anda. Proyek AspireSample.AppHost menambahkan proyek AspireSample.ApiService dan AspireSample.Web ke model aplikasi. Ini juga mendeklarasikan nama mereka sebagai "webfrontend" untuk front end Blazor, "apiservice" untuk referensi proyek API. Selain itu, sumber daya server Redis berlabel "cache" ditambahkan. Nama-nama ini digunakan untuk mengonfigurasi penemuan layanan dan komunikasi antara proyek di aplikasi Anda.

Aplikasi front end mendefinisikan HttpClient bertipe yang digunakan untuk berkomunikasi dengan proyek API.

namespace AspireSample.Web;

public class WeatherApiClient(HttpClient httpClient)
{
    public async Task<WeatherForecast[]> GetWeatherAsync(
        int maxItems = 10,
        CancellationToken cancellationToken = default)
    {
        List<WeatherForecast>? forecasts = null;

        await foreach (var forecast in 
            httpClient.GetFromJsonAsAsyncEnumerable<WeatherForecast>(
                "/weatherforecast", cancellationToken))
        {
            if (forecasts?.Count >= maxItems)
            {
                break;
            }
            if (forecast is not null)
            {
                forecasts ??= [];
                forecasts.Add(forecast);
            }
        }

        return forecasts?.ToArray() ?? [];
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

HttpClient telah dikonfigurasi untuk menggunakan pencarian layanan. Pertimbangkan kode berikut dari file proyek AspireSample.Web:

using AspireSample.Web;
using AspireSample.Web.Components;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();
builder.AddRedisOutputCache("cache");

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseAntiforgery();

app.UseOutputCache();

app.MapStaticAssets();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

Kode sebelumnya:

Memanggil AddServiceDefaults untuk mengonfigurasi pengaturan default bersama untuk aplikasi.
Memanggil AddRedisOutputCache dengan connectionName yang sama yang digunakan saat menambahkan kontainer Redis"cache" ke model aplikasi. Ini mengonfigurasi aplikasi untuk menggunakan Redis untuk pengelolaan cache output.
Memanggil AddHttpClient dan mengonfigurasi HttpClient.BaseAddress menjadi "https+http://apiservice". Ini adalah nama yang digunakan saat menambahkan proyek API ke model aplikasi, dan dengan konfigurasi penemuan layanan, secara otomatis diarahkan ke alamat yang benar dari proyek API.

Untuk informasi selengkapnya, lihat Membuat permintaan HTTP dengan kelas HttpClient.

Lihat juga

Langkah berikutnya

Tutorial : Menambahkan .NET Aspire ke aplikasi .NET yang sudah ada