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

Hostowanie integracji NATS dla modeli .NET Aspire modeluje NATSserver jako typ NatsServerResource. Aby uzyskać dostęp do tego typu, zainstaluj pakiet NuGet 📦Aspire.Hosting.Nats 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 NATSserver

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

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 NATSserver na komputerze lokalnym. Odwołanie do NATSserver (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 NATSserver, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Dokumentacja istniejących zasobów.

Dodawanie zasobu NATSserver za pomocą usługi JetStream

Aby dodać NATS JetStream do zasobu NATSserver, 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).

Dodawanie zasobu NATSserver z woluminem danych

Aby dodać wolumin danych do zasobu NATSserver, wywołaj metodę WithDataVolume w zasobie NATSserver:

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 służy do utrwalania NATSserver danych poza czasem życia kontenera. Wolumin danych jest instalowany w ścieżce /var/lib/nats w kontenerze NATSserver. 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.

Dodaj zasób NATSserver z przymocowaniem powiązania danych

Aby dodać przymocowanie danych do zasobu NATSserver, 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.

Instalacje powiązania danych polegają na systemie plików maszyny hosta w celu utrwalania NATSserver danych między ponownymi uruchomieniami kontenera. Punkt montowania danych jest montowany na ścieżce C:\NATS\Data w systemie Windows (lub /NATS/Data w Unix) na maszynie hosta w kontenerze NATSserver. 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 NATSserver. Sprawdzenie stanu zdrowia weryfikuje, czy NATSserver działa i czy można nawiązać z nim połączenie.

Integracja hostingu polega na użyciu pakietu NuGet 📦 AspNetCore.HealthChecks.Nats.

integracja Client

Aby rozpocząć pracę z integracją .NET AspireNATSclient, zainstaluj 📦Aspire.NATSpakiet NuGet platformy .Net w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z NATSclient. Integracja NATSclient rejestruje wystąpienie INatsConnection , którego można użyć do interakcji z NATS.

dotnet add package Aspire.NATS.Net

Dodaj NATSclient

W pliku Program.cs konsumującego projekt clientużyj metody rozszerzenia AddNatsClient na dowolnym IHostApplicationBuilder, aby zarejestrować INatsConnection do użycia przy użyciu 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 NATSserver w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu NATSserver.

Następnie można użyć wstrzykiwania zależności, aby pobrać instancję INatsConnection. Aby na przykład pobrać client 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 oznaczenie NATSclient

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 NATSclientJSON, 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 NATSserver 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ż