integrasi .NET AspireNATS

Meliputi: integrasi hosting dan integrasi Client

NATS adalah sistem olahpesan berkinerja tinggi, aman, terdistribusi. Integrasi .NET AspireNATS memungkinkan Anda terhubung ke instans NATS yang ada, atau membuat instans baru dari .NET dengan gambar kontainer docker.io/library/nats.

Integrasi hosting

NATS integrasi hosting untuk .NET Aspire memodelkan server NATS sebagai jenis NatsServerResource. Untuk mengakses jenis ini, pasang paket NuGet 📦Aspire.Hosting.Nats di proyek host aplikasi, kemudian tambahkan dengan pengonfigurasi.

dotnet add package Aspire.Hosting.Nats

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

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

Menambahkan sumber daya server NATS

Di proyek host aplikasi Anda, panggil AddNats pada instans builder untuk menambahkan sumber daya server NATS:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

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

Saat .NET.NET Aspire menambahkan gambar kontainer ke host aplikasi, seperti yang ditunjukkan dalam contoh sebelumnya dengan gambar docker.io/library/nats, gambar tersebut membuat instans server NATS baru di komputer lokal Anda. Referensi ke server NATS Anda (variabel nats) ditambahkan ke ExampleProject.

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama "nats". Untuk informasi selengkapnya, lihat siklus hidup sumber daya kontainer.

Menambahkan sumber daya server NATS dengan JetStream

Untuk menambahkan NATS JetStream ke sumber daya server NATS, panggil metode WithJetStream:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithJetStream();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

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

Fungsionalitas NATS JetStream menyediakan mesin persistensi bawaan yang disebut JetStream yang memungkinkan pesan disimpan dan diputar ulang di lain waktu.

Menambahkan sumber daya server NATS dengan parameter autentikasi

Ketika Anda ingin secara eksplisit memberikan nama pengguna dan kata sandi, Anda dapat memberikannya sebagai parameter. Pertimbangkan contoh alternatif berikut:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var nats = builder.AddNats(
    name: "nats",
    userName: username,
    password: password);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);


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

Untuk informasi selengkapnya, lihat Parameter eksternal.

Tambahkan sumber daya server NATS dengan volume data

Untuk menambahkan volume data ke sumber daya server NATS, panggil metode WithDataVolume pada sumber daya server NATS:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

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

Volume data digunakan untuk mempertahankan data server NATS di luar siklus hidup kontainernya. Volume data dipasang di jalur /var/lib/nats di kontainer server NATS. Nama dihasilkan secara acak kecuali Anda memberikan set parameter name. Untuk informasi selengkapnya tentang volume data dan detail mengapa mereka lebih disukai daripada pemanggungan bind , lihat dokumen Docker berjudul Volumes:.

Menambahkan sumber daya server NATS dengan pemasangan ikatan data

Untuk menambahkan pemasangan ikatan data ke sumber daya server NATS, panggil metode WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

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

Pemasangan bind data mengandalkan sistem berkas pada mesin host untuk menyimpan data server NATS setiap kali kontainer di-restart. "Data bind mount dipasang di C:\NATS\Data pada jalur Windows (atau /NATS/Data di Unix) pada komputer host dalam kontainer server NATS." Untuk informasi selengkapnya tentang pemasangan ikatan data, lihat dokumen Docker: Pemasangan ikatan.

Menjalankan pemeriksaan kesehatan integrasi

Integrasi hosting NATS secara otomatis menambahkan pemeriksaan kesehatan untuk sumber daya server NATS. Pemeriksaan kesehatan memverifikasi bahwa server NATS sedang berjalan dan bahwa koneksi dapat dibuat untuknya.

Integrasi hosting bergantung pada paket 📦 AspNetCore.HealthChecks.Nats NuGet.

Client integrasi

Untuk memulai integrasi klien .NET AspireNATS, instal paket NuGet 📦Aspire.NATS.Net dalam proyek yang menggunakan klien, yaitu proyek aplikasi yang memakai klien NATS. Integrasi klien NATS mendaftarkan instans INatsConnection yang dapat Anda gunakan untuk berinteraksi dengan NATS.

dotnet add package Aspire.NATS.Net

<PackageReference Include="Aspire.NATS.Net"
                  Version="*" />

Menambahkan klien NATS

Dalam file Program.cs dari proyek yang menggunakan klien Anda, panggil metode ekstensi AddNatsClient pada setiap IHostApplicationBuilder untuk mendaftarkan INatsConnection sehingga dapat digunakan melalui wadah injeksi ketergantungan. Metode ini mengambil parameter nama koneksi.

builder.AddNatsClient(connectionName: "nats");

Anda kemudian dapat mengambil instans INatsConnection menggunakan injeksi dependensi. Misalnya, untuk mengambil klien dari layanan:

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

Untuk informasi lebih lanjut mengenai injeksi dependensi, lihat .NET.

Menambahkan klien NATS yang berbasis kunci

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans INatsConnection dengan nama koneksi yang berbeda. Untuk mendaftarkan klien kunci NATS, panggil metode AddKeyedNatsClient.

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

Kemudian Anda dapat mengambil kembali instans IConnection dengan menggunakan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

Untuk informasi selengkapnya tentang layanan dengan kunci, lihat .NET injeksi dependensi: layanan dengan kunci.

Konfigurasi

Integrasi .NET AspireNATS menyediakan beberapa opsi untuk mengonfigurasi koneksi NATS berdasarkan persyaratan dan konvensi proyek Anda.

Menggunakan string koneksi

Berikan nama string koneksi saat Anda memanggil builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

String koneksi diambil dari bagian konfigurasi ConnectionStrings:

{
  "ConnectionStrings": {
    "nats": "nats://nats:4222"
  }
}

Lihat dokumentasi ConnectionString untuk informasi selengkapnya tentang cara memformat string koneksi ini.

Menggunakan penyedia konfigurasi

Integrasi .NET AspireNATS mendukung Microsoft.Extensions.Configuration. Ini memuat NatsClientSettings dari konfigurasi dengan menggunakan kunci Aspire:Nats:Client. Cuplikan berikut adalah contoh file appsettings.json yang mengonfigurasi beberapa opsi:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://nats:4222",
        "DisableHealthChecks": true,
        "DisableTracing": true
      }
    }
  }
}

Untuk skema integrasi klien lengkap NATSJSON, lihat Aspire.NATS.Net/ConfigurationSchema.json.

Menggunakan delegasi sebaris

Teruskan delegasi Action<NatsClientSettings> configureSettings untuk menyiapkan beberapa atau semua opsi secara inline, misalnya untuk menonaktifkan pemeriksaan kesehatan dari dalam kode:

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks  = true);

NATS dalam manifes .NET Aspire

NATS bukan bagian dari manifes penyebaran .NET Aspire. Disarankan agar Anda menyiapkan sebuah server produksi NATS yang aman di luar .NET Aspire.

Client pemeriksaan kesehatan integrasi

Secara default, integrasi .NET.NET Aspire memungkinkan pemeriksaan kesehatan untuk semua layanan. Untuk informasi selengkapnya, lihat gambaran umum integrasi .NET.NET Aspire.

Integrasi .NET AspireNATS menangani hal berikut:

• Terintegrasi dengan titik akhir HTTP /health, yang menentukan semua pemeriksaan kesehatan terdaftar harus lulus agar aplikasi dianggap siap menerima lalu lintas.

Pengamatan dan telemetri

.NET .NET Aspire integrasi secara otomatis menyiapkan konfigurasi Pengelogan, Pelacakan, dan Metrik, yang terkadang dikenal sebagai pilar pengamatan. Untuk informasi selengkapnya tentang pengamatan integrasi dan telemetri, lihat gambaran umum integrasi .NET.NET Aspire. Bergantung pada layanan pendukung, beberapa integrasi mungkin hanya mendukung beberapa fitur ini. Misalnya, beberapa integrasi mendukung pengelogan dan pelacakan, tetapi bukan metrik. Fitur telemetri juga dapat dinonaktifkan menggunakan teknik yang disajikan di bagian Konfigurasi .

Penebangan / Pencatatan

Integrasi .NET AspireNATS menggunakan kategori log berikut:

• NATS

Menelusuri

Integrasi .NET AspireNATS memancarkan aktivitas pelacakan berikut:

• NATS.Net

Lihat juga

• NATS .Net panduan cepat
• .NET .NET Aspire integrasi
• .NET Aspire GitHub repo