Udostępnij za pośrednictwem

integracja .NET AspireNATS

  • Artykuł

obejmuje:integrację hostingu oraz integrację Client

NATS to wysokowydajny, bezpieczny, rozproszony system obsługi komunikatów. Integracja .NET AspireNATS umożliwia połączenie z istniejącymi instancjami NATS lub utworzenie nowych instancji z .NET przy użyciu obrazu kontenera docker.io/library/nats.

Integracja hostingu

NATS integracja hostingu dla modeli .NET Aspire modeluje serwer NATS jako typ NatsServerResource. Aby uzyskać dostęp do tego typu, zainstaluj . Hosting.Nats pakiet NuGet w projekcie hosta aplikacji , a następnie dodaj go za pomocą konstruktora.

dotnet add package Aspire.Hosting.Nats

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobu serwera NATS

W projekcie hosta aplikacji wywołaj AddNats w wystąpieniu builder, aby dodać zasób serwera NATS:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem docker.io/library/nats, tworzy nowe wystąpienie serwera NATS na komputerze lokalnym. Odwołanie do serwera NATS (zmiennej nats) jest dodawane do ExampleProject.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie "nats". Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym serwerem NATS, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Dokumentacja istniejących zasobów.

Dodawanie zasobu serwera NATS za pomocą usługi JetStream

Aby dodać NATS JetStream do zasobu serwera NATS, wywołaj metodę 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...

Funkcjonalność NATS JetStream oferuje wbudowany mechanizm trwałości zwany JetStream, który pozwala na przechowywanie i późniejsze odtwarzanie komunikatów. Opcjonalnie możesz podać parametr srcMountPath, aby określić ścieżkę do katalogu danych JetStream na maszynie hosta (podana ścieżka montowania jest mapowana na argument -sd kontenera).

Dodaj zasób serwera NATS z woluminem danych

Aby dodać wolumin danych do zasobu serwera NATS, wywołaj metodę WithDataVolume w zasobie serwera 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...

Wolumin danych jest używany do utrwalania danych serwera NATS poza cyklem życia kontenera. Wolumen danych jest zamontowany w ścieżce /var/lib/nats w kontenerze serwera NATS. Nazwa jest generowana losowo, chyba że zostanie określony parametr name. Aby uzyskać więcej informacji na temat danych woluminów i szczegóły dotyczące preferowania ich nad instalacjami wiązań , zobacz dokumenty Docker: woluminy.

Dodawanie zasobu serwera NATS z instalacją powiązania danych

Aby dodać instalację powiązania danych do zasobu serwera NATS, wywołaj metodę 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...

Ważny

Powiązane montowanie danych ma ograniczoną funkcjonalność w porównaniu z woluminami , które oferują lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak instalacje wiązania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, idealne do programowania i testowania, w których potrzebne są zmiany w czasie rzeczywistym.

Montaże powiązań danych polegają na systemie plików maszyny hosta do utrwalania danych serwera NATS podczas ponownych uruchomień kontenera. Powiązanie danych jest zamontowane na C:\NATS\Data w systemie Windows (lub /NATS/Data na Unix) na ścieżce na maszynie hosta w kontenerze serwera NATS. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Przeprowadzanie kontroli stanu integracji

Integracja hostowania NATS automatycznie dodaje kontrolę kondycji zasobu serwera NATS. Sprawdzanie kondycji sprawdza, czy serwer NATS jest uruchomiony i czy można nawiązać z nim połączenie.

Integracja hostingu opiera się na pakiecie 📦 AspNetCore.HealthChecks.Nats NuGet.

integracja Client

Aby rozpocząć pracę z integracją klienta .NET AspireNATS, zainstaluj 📦Aspire.NATS.Net pakiet NuGet w projekcie korzystającym z klienta, czyli w projekcie aplikacji używającej klienta NATS. Integracja klienta NATS rejestruje wystąpienie INatsConnection, którego można użyć do interakcji z NATS.

dotnet add package Aspire.NATS.Net

Dodaj klienta NATS

W pliku Program.cs projektu korzystającego z klienta wywołaj metodę rozszerzenia AddNatsClient na dowolnym IHostApplicationBuilder, aby zarejestrować INatsConnection do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddNatsClient(connectionName: "nats");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu serwera NATS w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodaj NATS zasób serwera.

Następnie można użyć wstrzykiwania zależności, aby pobrać instancję INatsConnection. Aby na przykład pobrać klienta z usługi:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj klienta oznaczonego kluczem NATS

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień INatsConnection z różnymi nazwami połączeń. Aby zarejestrować klientów z kluczem NATS, użyj metody AddKeyedNatsClient:

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

Następnie można pobrać instancje IConnection za pomocą wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług oznaczonych kluczami, odwołaj się do ".NET wstrzykiwanie zależności: usługi oznaczone kluczami".

Konfiguracja

Integracja .NET AspireNATS oferuje wiele opcji konfigurowania połączenia NATS na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

Podaj nazwę parametrów połączenia podczas wywoływania builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

Parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji na temat formatowania tego ciągu połączenia, zobacz dokumentację ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireNATS obsługuje Microsoft.Extensions.Configuration. Ładuje NatsClientSettings z konfiguracji przy użyciu klucza Aspire:Nats:Client. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji klienta NATSJSON, zobacz Aspire.NATS.Net/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Przekaż delegata Action<NatsClientSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia kontroli kondycji z kodu:

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

NATS w manifeście .NET Aspire

NATS nie jest częścią manifestu wdrożeniowego .NET Aspire. Zaleca się skonfigurowanie bezpiecznego serwera NATS produkcyjnego poza .NET Aspire.

Client kontrola stanu integracji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireNATS obsługuje następujące elementy:

  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane testy kondycji muszą zostać zaliczone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Rejestrowanie

Integracja .NET AspireNATS używa następujących kategorii dzienników:

  • NATS

Śledzenie

Integracja .NET AspireNATS emituje następujące działania śledzenia:

  • NATS.Net

Zobacz też