.NET Aspire NATS 통합

아티클
01/23/2025

NATS 고성능의 안전한 분산 메시징 시스템입니다. .NET Aspire NATS 통합을 사용하면 기존 NATS 인스턴스에 연결하거나 .NET사용하여 docker.io/library/nats 새 인스턴스를 만들 수 있습니다.

호스팅 통합

NATS .NET Aspire 호스팅 통합은 NATS 서버를 NatsServerResource 유형으로 모델화합니다. 이 형식에 액세스하려면 📦Aspire설치합니다. Hosting.Nats는 앱 호스트 프로젝트에서 NuGet 패키지를 다음 작성기를 사용하여 추가합니다.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Nats

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

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성을 관리하기를 참조하십시오.

NATS 서버 리소스 추가

앱 호스트 프로젝트에서 AddNats 인스턴스에서 builder 호출하여 NATS 서버 리소스를 추가합니다.

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 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하는 경우 로컬 컴퓨터에 새 NATS 서버 인스턴스를 만듭니다. NATS 서버(nats 변수)에 대한 참조가 ExampleProject에 추가되었습니다.

WithReference 메서드는 ExampleProject 내에서 "nats"라는 이름의 연결을 구성합니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

팁

기존 NATS 서버에 연결하려는 경우 대신 AddConnectionString 호출합니다. 자세한 내용은 기존 리소스를 참조하세요 .

JetStream을 사용하여 NATS 서버 리소스 추가

NATS 서버 리소스에 NATS 추가하려면 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이라는 기본 제공 지속성 엔진을 제공합니다. 필요에 따라 호스트 컴퓨터에서 JetStream 데이터 디렉터리의 경로를 지정하는 srcMountPath 매개 변수를 제공할 수 있습니다(제공된 탑재 경로는 컨테이너의 -sd 인수에 매핑됨).

데이터 볼륨을 사용하여 NATS 서버 리소스 추가

NATS 서버 리소스에 데이터 볼륨을 추가하려면 WithDataVolume 서버 리소스에서 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...

데이터 볼륨은 컨테이너의 수명 주기 외부에 NATS 서버 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 /var/lib/nats 서버 컨테이너의 NATS 경로에 탑재됩니다. name 매개 변수 집합을 제공하지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨참조하세요.

데이터 바인드 마운트를 사용하여 NATS 서버 리소스 추가

NATS 서버 리소스에 데이터 바인딩 탑재를 추가하려면 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...

중요하다

데이터 바인딩 탑재 볼륨비해 기능이 제한되므로 성능, 이식성 및 보안이 향상되어 프로덕션 환경에 더 적합합니다. 그러나 바인딩 탑재를 사용하면 호스트 시스템의 파일에 직접 액세스하고 수정할 수 있으므로 실시간 변경이 필요한 개발 및 테스트에 적합합니다.

데이터 바인딩 탑재는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너를 다시 시작할 때 NATS 서버 데이터를 유지합니다. 호스트 컴퓨터의 C:\NATS\Data 서버 컨테이너에서 데이터 바인드 마운트는 Windows의 /NATS/Data 경로(또는 Unix의 NATS 경로)에 탑재됩니다. 데이터 바인드 마운트에 대한 자세한 내용은 Docker 문서: 바인드 마운트를 참조하세요.

통합 호스팅 건강 상태 검사

NATS 호스팅 통합은 NATS 서버 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 NATS 서버가 실행 중이며 서버에 대한 연결을 설정할 수 있는지 확인합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.Nats NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire NATS 클라이언트 통합을 시작하려면 📦Aspire을 설치하세요. 이는NATS.Net NuGet 패키지를 사용하는 프로젝트, 즉 NATS 클라이언트를 사용하는 애플리케이션에 해당합니다. NATS 클라이언트 통합은 와 상호 작용할 수 있도록 NATS 인스턴스를 등록합니다.

.NET CLI
PackageReference

dotnet add package Aspire.NATS.Net

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

NATS 클라이언트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서, 모든 AddNatsClient에 대해 IHostApplicationBuilder 확장 메서드를 호출하여 종속성 주입 컨테이너를 통해 사용할 INatsConnection을(를) 등록합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddNatsClient(connectionName: "nats");

팁

connectionName 매개 변수는 앱 호스트 프로젝트에서 NATS 서버 리소스를 추가할 때 사용되는 이름과 일치해야 합니다. 자세한 내용은 NATS 서버 리소스추가를 참조하세요.

그런 다음 종속성 주입을 사용하여 INatsConnection 인스턴스를 검색할 수 있습니다. 예를 들어 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

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

종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

지정된 NATS 클라이언트 추가

여러 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
      }
    }
  }
}

전체 NATS 클라이언트 통합 JSON 스키마는 Aspire을 참조하세요.NATS.Net/ConfigurationSchema.json.

인라인 대리자 사용

Action<NatsClientSettings> configureSettings 대리자를 전달하여 코드에서 상태 검사를 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정합니다.

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

NATS 매니페스트의 .NET Aspire

NATS은 .NET Aspire배포 매니페스트의 부분이 아닙니다. NATS외부에서 안전한 프로덕션 .NET Aspire 서버를 설정하는 것이 좋습니다.

Client 통합 상태 점검

기본적으로 .NET.NET Aspire 통합은 모든 서비스에 대해 상태 검사를 활성화합니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.

.NET Aspire NATS 통합은 다음을 처리합니다.

등록된 모든 상태 검사가 통과해야 하고 이를 통해 앱이 트래픽을 수락할 준비가 된 것으로 간주됨을 지정하는 /health HTTP 엔드포인트와 통합됩니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성핵심 요소라고도 . 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire NATS 통합은 다음 로그 범주를 사용합니다.

NATS

추적

.NET Aspire NATS 통합은 다음과 같은 추적 활동을 내보낸다.

NATS.Net

다음을 통해 공유