Udostępnij za pośrednictwem

.NET Aspire Redis * integracja rozproszonego buforowania ®

  • Artykuł

obejmuje: integracja hostingu oraz integracja Client

Dowiedz się, jak używać integracji rozproszonego buforowania .NET AspireRedis. Biblioteka Aspire.StackExchange.Redis.DistributedCaching jest używana do rejestrowania dostawcy IDistributedCache, który jest wspierany przez serwer Redis z użyciem obrazu kontenera docker.io/library/redis.

Dowiedz się, jak używać integracji rozproszonego buforowania .NET AspireRedis. Biblioteka Aspire.StackExchange.Redis.DistributedCaching służy do rejestrowania dostawcy IDistributedCache obsługiwanego przez serwer Garnet przy użyciu obrazu kontenera ghcr.io/microsoft/garnet.

Dowiedz się, jak używać integracji rozproszonego buforowania .NET AspireRedis. Biblioteka Aspire.StackExchange.Redis.DistributedCaching służy do rejestrowania dostawcy IDistributedCache wspieranego przez serwer Valkey przy użyciu obrazu kontenera docker.io/valkey/valkey.

Integracja hostingu

Model integracji hostingu Redis przedstawia zasób Redis jako typ RedisResource. Aby uzyskać dostęp do tego typu i interfejsów API do przedstawienia ich jako zasoby w projekcie hostującym aplikację , dodaj pakiet NuGet 📦Aspire.Hosting.Redis.

dotnet add package Aspire.Hosting.Redis

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

Dodawanie zasobu Redis

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

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

// 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/Redis/Redis, tworzy nową instancję Redis na lokalnej maszynie. Odwołanie do twojego zasobu Redis (zmiennej cache) zostało dodane do ExampleProject.

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

Napiwek

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

Dodawanie zasobu Redis za pomocą usługi Redis Insights

Aby dodać Redis Insights do zasobu Redis, wywołaj metodę WithRedisInsight:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisInsight();

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

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

Redis Insights to bezpłatny interfejs graficzny do analizy danych Redis we wszystkich systemach operacyjnych i Redis wdrożeniach przy użyciu naszego asystenta sztucznej inteligencji, Redis Copilot. .NET .NET Aspire dodaje kolejny obraz kontenera docker.io/redis/redisinsight do hosta aplikacji, który uruchamia aplikację dowódcy.

Uwaga

Aby skonfigurować port hosta dla RedisInsightResource, wykonaj wywołanie do interfejsu API WithHostPort i podaj żądany numer portu.

Dodawanie zasobu Redis za pomocą dowódcy Redis

Aby dodać Redis Commander do zasobu Redis, wywołaj metodę WithRedisCommander:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisCommander();

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

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

Redis Commander to aplikacja internetowa Node.js używana do wyświetlania, edytowania i zarządzania bazą danych Redis. .NET .NET Aspire dodaje kolejny obraz kontenera docker.io/rediscommander/redis-commander do hosta aplikacji, który uruchamia aplikację dowódcy.

Wskazówka

Aby skonfigurować port hosta dla RedisCommanderResource, wykonaj wywołanie do interfejsu API WithHostPort i podaj żądany numer portu.

Dodawanie zasobu Redis z woluminem danych

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

Wolumen danych służy do utrwalania danych Redis poza cyklem życia jego kontenera. Wolumin danych jest instalowany w ścieżce /data w kontenerze Redis, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat wolumenów danych i szczegółów na temat tego, dlaczego preferowane są od instalacji wiązań, zobacz w Docker dokumentacji: Woluminy.

Dodaj zasób Redis z zamontowaniem powiązania danych

Aby dodać związanie danych do zasobu Redis, wywołaj metodę WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataBindMount(
                       source: @"C:\Redis\Data",
                       isReadOnly: false);

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

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

Ważny

Instalacje powiązań danych mają 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 powiązane systemy montowania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdy potrzebne są zmiany w czasie rzeczywistym.

Montowanie powiązań danych polega na systemie plików maszyny hosta do przechowywania danych Redis w trakcie restartów kontenera. Powiązanie danych jest montowane na ścieżce C:\Redis\Data w systemie Windows (lub /Redis/Data w Unix) na maszynie hosta w kontenerze Redis. Aby uzyskać więcej informacji na temat wiązań danych, zobacz dokumentację: Docker Źródła: Zamocowania wiązań.

Dodaj zasób Redis z zachowaniem trwałości

Aby dodać trwałość do zasobu Redis, wywołaj metodę WithPersistence, podając jako argument wolumin danych lub podmontowanie danych.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

Powyższy kod zapewnia trwałość zasobowi Redis przez tworzenie migawek danych Redis zgodnie z określonym interwałem i progiem. interval to okres między eksportami migawek, a keysChangedThreshold to liczba operacji zmiany klucza wymagana do wyzwolenia migawki. Aby uzyskać więcej informacji na temat trwałości, zobacz Redis docs: Trwałość.

Integracja hostingu Garnet modeluje zasób Garnet jako typ GarnetResource. Aby uzyskać dostęp do tego typu i interfejsów API, które umożliwiają dodanie go do pakietu NuGet 📦Aspire.Hosting.Garnet w projekcie hosta aplikacji.

dotnet add package Aspire.Hosting.Garnet

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

Dodawanie zasobu Garnet

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache");

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

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

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano we wcześniejszym przykładzie z obrazem ghcr.io/microsoft/garnet, tworzy nowe wystąpienie Garnet na komputerze lokalnym. Odwołanie do zasobu Garnet (zmienna cache) zostaje dodane do ExampleProject.

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

Napiwek

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

Dodawanie zasobu Garnet z woluminem danych

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

Wolumen danych służy do utrwalania danych Garnet poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data w kontenerze Garnet i gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat wolumenów danych i szczegółów na temat tego, dlaczego preferowane są od instalacji wiązań, zobacz w Docker dokumentacji: Woluminy.

Dodaj zasób Garnet z montowaniem wiązania danych

Aby dodać punkt montowania danych do zasobu Garnet, wywołaj metodę WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataBindMount(
                       source: @"C:\Garnet\Data",
                       isReadOnly: false);

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

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

Ważny

Instalacje powiązań danych mają 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 powiązane systemy montowania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdy potrzebne są zmiany w czasie rzeczywistym.

Połączenia wiązania danych są zależne od systemu plików maszyny hosta w celu utrwalania danych Garnet podczas ponownych uruchomień kontenera. Powiązanie danych jest zamontowane na ścieżce C:\Garnet\Data w systemie Windows (lub /Garnet/Data na Unix) na maszynie hosta w kontenerze Garnet. Aby uzyskać więcej informacji na temat wiązań danych, zobacz dokumentację: Docker Źródła: Zamocowania wiązań.

Dodaj zasób Garnet z zachowaniem trwałości

Aby zasób Garnet był trwały, wywołaj metodę WithPersistence, używając albo wolumenu danych, albo montowania wiązań danych.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

Powyższy kod dodaje trwałość zasobowi Redis przez tworzenie migawek danych Garnet w określonym interwale i progu. interval to okres między eksportami migawek, a keysChangedThreshold to liczba operacji zmiany klucza wymagana do wyzwolenia migawki. Aby uzyskać więcej informacji na temat trwałości, zobacz Redis docs: Trwałość.

Integracja Valkey modeluje zasób Valkey jako typ ValkeyResource. Aby uzyskać dostęp do tego typu i interfejsów API, które umożliwiają dodanie go do pakietu NuGet 📦Aspire.Hosting.Valkey w projekcie hosta aplikacji.

dotnet add package Aspire.Hosting.Valkey

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

Dodawanie zasobu Valkey

W projekcie hosta aplikacji wywołaj AddValkey na instancji builder, aby dodać zasób Valkey.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache");

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

// 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/valkey/valkey, na komputerze lokalnym tworzona jest nowa instancja Valkey. Odwołanie do zasobu Valkey (zmiennej cache) jest dodawane do elementu ExampleProject.

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

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącą instancją Valkey, wywołaj AddConnectionString. Aby uzyskać więcej informacji, zobacz Odniesienie do istniejących zasobów.

Dodawanie zasobu Valkey z woluminem danych

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

Wolumin danych jest używany do utrwalania danych Valkey poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data w kontenerze Valkey, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat wolumenów danych i szczegółów na temat tego, dlaczego preferowane są od instalacji wiązań, zobacz w Docker dokumentacji: Woluminy.

Dodaj zasób Valkey z użyciem powiązania danych

Aby dodać powiązanie danych z zasobem Valkey, wywołaj metodę WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataBindMount(
                       source: @"C:\Valkey\Data",
                       isReadOnly: false);

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

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

Ważny

Instalacje powiązań danych mają 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 powiązane systemy montowania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do rozwoju i testowania, gdy potrzebne są zmiany w czasie rzeczywistym.

Mocowania danych polegają na systemie plików maszyny hosta, aby przechowywać dane Valkey między ponownymi uruchomieniami kontenera. Montowanie dowiązania danych odbywa się w punkcie C:\Valkey\Data w systemie Windows (lub w punkcie /Valkey/Data na Unix) na maszynie hosta w ramach kontenera Valkey. Aby uzyskać więcej informacji na temat wiązań danych, zobacz dokumentację: Docker Źródła: Zamocowania wiązań.

Dodaj zasób Valkey ze stałością

Aby dodać trwałość do zasobu Valkey, wywołaj metodę WithPersistence za pomocą woluminu danych lub instalacji powiązania danych:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

Powyższy kod zapewnia trwałość zasobu Redis poprzez wykonywanie zrzutów danych Valkey w określonych odstępach czasu i po osiągnięciu określonego progu. interval to okres między eksportami migawek, a keysChangedThreshold to liczba operacji zmiany klucza wymagana do wyzwolenia migawki. Aby uzyskać więcej informacji na temat trwałości, zobacz Redis docs: Trwałość.

Sprawdzanie kondycji integracji hostingu

Redis integracja hostingu automatycznie dodaje kontrolę kondycji dla odpowiedniego typu zasobu. Kontrola kondycji sprawdza, czy serwer jest uruchomiony i czy można nawiązać z nim połączenie.

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

Client integracja

Aby rozpocząć pracę z integracją rozproszonego buforowania .NET AspireRedis, zainstaluj pakiet NuGet 📦Aspire.StackExchange.Redis.DistributedCaching w projekcie, który korzysta z klienta, tj. w projekcie aplikacji używającej klienta rozproszonego buforowania Redis. Integracja klienta Redis rejestruje wystąpienie IDistributedCache, którego można użyć do interakcji z Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Dodaj klienta Redis

W pliku Program.cs w projekcie korzystającym z klienta wywołaj rozszerzenie AddRedisDistributedCache, aby zarejestrować wymagane usługi do buforowania rozproszonego i dodać IDistributedCache do używania za pośrednictwem kontenera wstrzykiwania zależności.

builder.AddRedisDistributedCache(connectionName: "cache");

Napiwek

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

Napiwek

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Valkey w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz sekcję Dodawanie zasobu Valkey.

Można następnie pobrać wystąpienie IDistributedCache za pomocą wstrzykiwania zależności. Na przykład, aby pobrać pamięć podręczną z usługi:

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

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

Dodaj klienta Redis z kluczem

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień IDistributedCache z różnymi nazwami połączeń. Aby zarejestrować klientów z kluczami Redis, wywołaj metodę AddKeyedRedisDistributedCache.

builder.AddKeyedRedisDistributedCache(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");

Przy użyciu wstrzykiwania zależności można następnie pobrać wystąpienia IDistributedCache. Aby na przykład pobrać połączenie z przykładowej usługi:

public class ExampleService(
    [FromKeyedServices("chat")] IDistributedCache chatCache,
    [FromKeyedServices("product")] IDistributedCache productCache)
{
    // Use caches...
}

Aby uzyskać więcej informacji na temat usług bazujących na kluczach, zobacz .NET wstrzykiwanie zależności: usługi bazujące na kluczach.

Konfiguracja

Integracja rozproszonego buforowania .NET AspireRedis udostępnia wiele opcji konfigurowania połączenia Redis na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddRedisDistributedCache:

builder.AddRedisDistributedCache("cache");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

Aby uzyskać więcej informacji na temat formatowania tego łańcucha połączenia, zobacz dokumentację konfiguracji Stack Exchange Redis.

Korzystanie z dostawców konfiguracji

Integracja rozproszonego buforowania .NET Aspire Stack Exchange Redis obsługuje Microsoft.Extensions.Configuration. Ładuje StackExchangeRedisSettings z konfiguracji przy użyciu klucza Aspire:StackExchange:Redis. Przykład appsettings.json, który konfiguruje niektóre opcje:

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Aby uzyskać pełny Redis schemat integracji klienta rozproszonego buforowania JSON, zobacz Aspire. StackExchange.Redis. DistributedCaching/ConfigurationSchema.json.

Użyj delegatów wbudowanych

Możesz również przekazać delegata Action<StackExchangeRedisSettings>, aby bezpośrednio w kodzie skonfigurować niektóre lub wszystkie opcje, na przykład DisableTracing:

builder.AddRedisDistributedCache(
    "cache",
    settings => settings.DisableTracing = true);

Można również skonfigurować ConfigurationOptions przy użyciu parametru delegata Action<ConfigurationOptions> configureOptions metody AddRedisDistributedCache. Na przykład aby ustawić limit czasu połączenia:

builder.AddRedisDistributedCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

Client kontrole stanu integracji

Domyślnie .NET.NET Aspireintegracje klienta mają kontrole stanu włączone dla wszystkich usług. Podobnie wiele .NET.NET Aspireintegracji hostingowych umożliwia endpunkty kontroli kondycji. Aby uzyskać więcej informacji, zobacz:

Integracja rozproszonego buforowania .NET AspireRedis obsługuje następujące elementy:

  • Dodaje sprawdzenie kondycji, gdy StackExchangeRedisSettings.DisableHealthChecks jest false, próbujące nawiązać połączenie z instancją kontenera.
  • Integruje się z punktem końcowym HTTP /health, który wymaga, aby wszystkie zarejestrowane kontrole sprawności były pomyślnie przeprowadzone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, 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 .

Wycinanie drzew и zarządzanie drewnem

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

  • Aspire.StackExchange.Redis
  • Microsoft.Extensions.Caching.StackExchangeRedis

Śledzenie

Integracja rozproszonego buforowania .NET AspireRedis spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Metryki

Integracja buforowania rozproszonego .NET AspireRedis domyślnie nie obsługuje metryk z uwagi na ograniczenia biblioteki StackExchange.Redis.

Zobacz też

*: Redis jest zastrzeżonym znakiem towarowym Redis Ltd. Wszelkie prawa, które istnieją, są zastrzeżone do Redis Ltd. Każde użycie przez firmę Microsoft jest przeznaczone tylko do celów referentalnych i nie wskazuje żadnych sponsorów, poparcia ani przynależności między Redis a firmą Microsoft. powrócić do góry?