.NET Aspire NATS 整合

發行項
12/20/2024

NATS 是高效能、安全的分散式傳訊系統。 .NET Aspire NATS 整合可讓您連線到現有的 NATS 實例，或使用 docker.io/library/nats從建立新的實例。

主機整合

NATS 整合為 .NET Aspire 模型，將 NATSserver 作為 NatsServerResource 類型。若要存取此類型，請在應用程式主機專案中安裝 .Hosting. NuGet 套件，然後使用生成器將其添加。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Nats

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

如需詳細資訊，請參閱 dotnet add package 或管理 .NET 應用程式中的套件相依性。

新增 NATSserver 資源

在應用程式主專案中，呼叫 AddNats 實例上的 builder，以新增 NATSserver 資源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

當 .NET.NET Aspire 將容器映像添加至應用程式主機時，如上述範例中所示使用 docker.io/library/nats 映像，它會在您的本機計算機上建立新的 NATSserver 實體。 NATS server 的參考（nats 變數）已新增至 ExampleProject。

WithReference 方法會在名為 ExampleProject的 "nats" 中設定連接。如需詳細資訊，請參閱容器資源生命週期。

提示

如果您想要連線到現有的 NATSserver，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

使用 JetStream 新增 NATSserver 資源

若要將 NATS JetStream 新增至 NATSserver 資源，請呼叫 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...

NATS JetStream 功能提供稱為 JetStream 的內建持續性引擎，可讓您稍後儲存和重新執行訊息。您可以選擇性地提供 srcMountPath 參數，以指定主計算機上的 JetStream 資料目錄路徑（提供的掛接路徑對應至容器的 -sd 自變數）。

根據數據量新增 NATSserver 資源

若要將數據磁碟區新增至 NATSserver 資源，請在 WithDataVolumeNATS 資源上呼叫 server 方法：

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...

數據磁碟區用來將 NATSserver 數據保存在其容器生命週期之外。資料磁碟區會掛接在 /var/lib/natsNATS 容器的 server 路徑上。除非您提供設定 name 參數，否則會隨機產生名稱。如需了解數據卷的詳細資訊，以及為何它們優於系結掛接的原因，請參閱 Docker 文件：卷。

新增具備數據綁定掛載的 NATSserver 資源

若要將數據系結掛接新增至 NATSserver 資源，請呼叫 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...

重要

相較於提供更佳效能、可攜性及安全性的卷宗，數據綁定掛載的功能有限，因此更適合於生產環境使用。不過，系結掛接允許直接存取和修改主機系統上的檔案，非常適合需要即時變更的開發和測試情境。

資料綁定掛載依賴於主機的檔案系統，以便在容器重新啟動時持續存儲 NATSserver 資料。數據系結掛接會掛接在 C:\NATS\Data/NATS/Data 容器中主計算機上的 Unix 上（或 NATS上 server）。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

主機整合健康檢查

主機整合 NATS 會自動新增 NATSserver 資源的健康檢查。健康檢查會確認 NATSserver 正在運行中，並且可以與之建立連線。

主機整合依賴 📦 AspNetCore.HealthChecks。Nats NuGet 套件。

Client 整合

若要開始使用 .NET AspireNATSclient 整合，請在 📦取用專案中安裝 client NuGet 套件，也就是使用 NATSclient的應用程式專案。 NATS client 整合會註冊 INatsConnection 實例，讓您可用來與 NATS互動。

.NET CLI
PackageReference

dotnet add package Aspire.NATS.Net

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

新增 NATSclient

在 Program.cs取用專案的 client 檔案中，在任何 AddNatsClient 上呼叫 IHostApplicationBuilder 擴充方法，以註冊 INatsConnection，以便透過相依性注入容器使用。方法會採用連接名稱參數。

builder.AddNatsClient(connectionName: "nats");

提示

connectionName 參數必須符合在應用程式主專案中新增 NATSserver 資源時所使用的名稱。如需詳細資訊，請參閱新增 NATSserver 資源。

接著，您可以使用相依注入來取得 INatsConnection 實例。例如，若要從服務擷取 client：

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

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增索引鍵 NATSclient

在某些情況下，您可能想要以不同的連線名稱註冊多個 INatsConnection 實例。若要註冊鍵入的 NATS 用戶端，請呼叫 AddKeyedNatsClient 方法：

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

然後，您可以使用相依性插入來擷取 IConnection 實例。例如，若要從範例服務擷取連線：

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

若要進一步了解鍵控服務，請參閱 .NET 相依性注入：鍵控服務。

配置

.NET Aspire NATS 整合提供多個選項，可根據專案的需求和慣例來設定 NATS 連線。

使用連接字串

當您呼叫 builder.AddNatsClient時，請提供連接字串的名稱：

builder.AddNatsClient(connectionName: "nats");

連接字串是從組態區段 ConnectionStrings 擷取：

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

如需如何格式化此連接字串的詳細資訊，請參閱 ConnectionString 檔。

使用組態提供者

.NET Aspire NATS 整合支援 Microsoft.Extensions.Configuration。它會使用 NatsClientSettings 鍵從配置載入 Aspire:Nats:Client。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

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

如需完整的 NATSclient 整合 JSON 架構，請參閱 Aspire。NATS.Net/ConfigurationSchema。json。

使用內聯委派

傳遞 Action<NatsClientSettings> configureSettings 委派來設置內嵌選項的一部分或全部，例如從程式碼中停用健康檢查：

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

NATS 指令清單中的 .NET Aspire

NATS 不屬於 .NET Aspire部署清單的一部分，。建議您在 NATS之外設定安全的生產 server.NET Aspire。

Client 整合健康檢查

根據預設，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire NATS 整合會處理下列事項：

與 /health HTTP 端點整合，指定所有已註冊的健康檢查都必須通過，應用程式才能被視為準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和計量組態，有時稱為 可檢視性要素。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire NATS 整合會使用下列記錄類別：

NATS

追蹤

.NET Aspire NATS 整合將產生下列追蹤活動：

NATS.Net

共用方式為