Sdílet prostřednictvím


.NET Aspire Redis®* integrace distribuovaného ukládání do mezipaměti

zahrnuje: integraci hostování a Client integraci

Naučte se používat .NET AspireRedis integraci distribuované mezipaměti. Knihovna Aspire.StackExchange.Redis.DistributedCaching slouží k registraci poskytovatele IDistributedCache, podporovaného serverem Redis s obrazem kontejneru docker.io/library/redis.

Naučte se používat .NET AspireRedis integraci distribuované mezipaměti. Knihovna Aspire.StackExchange.Redis.DistributedCaching se používá k registraci poskytovatele IDistributedCache, který je podporován serverem Garnet, s kontejnerovým obrazem ghcr.io/microsoft/garnet.

Naučte se používat .NET AspireRedis integraci distribuované mezipaměti. Knihovna Aspire.StackExchange.Redis.DistributedCaching se používá k registraci poskytovatele IDistributedCache podporovaného serverem Valkey s obrazem kontejneru docker.io/valkey/valkey.

Integrace hostování

Integrace hostingu Redis modeluje prostředek Redis jako typ RedisResource. Pokud chcete získat přístup k tomuto typu a rozhraním API, abyste je mohli vyjádřit jako prostředky v projektu app host, přidejte balíček NuGet 📦Aspire.Hosting.Redis:

dotnet add package Aspire.Hosting.Redis

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidej prostředek Redis

V projektu hostitele vaší aplikace zavolejte AddRedis na instanci builder a přidejte prostředek Redis.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí docker.io/Redis/Redis, vytvoří na místním počítači novou instanci Redis. Odkaz na váš prostředek Redis (proměnnou cache) je přidán k ExampleProject.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "cache". Pro více informací se podívejte na životní cyklus zdrojů kontejneru.

Spropitné

Pokud byste se raději připojili k existující instanci Redis, volejte místo toho AddConnectionString. Pro více informací viz Odkaz na stávající zdroje.

Přidání prostředku Redis pomocí Redis Insights

Pokud chcete do Redis prostředku přidat Redis Insights, zavolejte metodu 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 je bezplatné grafické rozhraní pro analýzu Redis dat ve všech operačních systémech a nasazeních Redis pomocí našeho asistenta AI Redis Copilot. .NET .NET Aspire přidá do hostitele aplikace, na kterém běží aplikace commander, další image kontejneru docker.io/redis/redisinsight.

Poznámka

Chcete-li nakonfigurovat port hostitele pro řetězec RedisInsightResource, zavolejte API WithHostPort a zadejte požadované číslo portu.

Přidání Redis prostředku pomocí Redis Commander

Chcete-li přidat Redis velitele do zdroje Redis, zavolejte metodu 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 je webová aplikace Node.js, která slouží k zobrazení, úpravám a správě Redis Database. .NET .NET Aspire přidá do hostitele aplikace, na kterém běží aplikace commander, další image kontejneru docker.io/rediscommander/redis-commander.

Spropitné

Chcete-li nakonfigurovat port hostitele pro řetězec RedisCommanderResource, zavolejte API WithHostPort a zadejte požadované číslo portu.

Přidejte prostředek Redis s datovým objemem

Pokud chcete do prostředku Redis přidat datový svazek, zavolejte metodu WithDataVolume prostředku 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...

Objem dat se používá k zachování Redis dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data v kontejneru Redis a když není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojeními typu bind, najdete v Docker dokumentaci: Svazky.

Přidejte zdroj Redis s připojením typu data bind mount

Chcete-li přidat datové připojení k prostředku Redis, zavolejte metodu 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...

Důležitý

Datové připojení typu bind mounts mají omezenou funkčnost ve srovnání s svazky, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je činí vhodnějšími pro produkční prostředí. Vazby však umožňují přímý přístup a úpravy souborů v hostitelském systému, ideální pro vývoj a testování, kde jsou změny v reálném čase potřebné.

Namapování datového úložiště spoléhá na systém souborů hostitelského počítače k zachování Redis dat při restartování kontejneru. Datové připojení je namontováno na C:\Redis\Data ve Windows (nebo /Redis/Data na Unix) na hostitelském počítači v kontejneru Redis. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidat Redis zdroj s trvalostí

Pokud chcete do prostředku Redis přidat trvalost, zavolejte metodu WithPersistence pomocí buď datového svazku, nebo připojení datového úložiště.

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

Předchozí kód přidá trvalost do prostředku Redis pořízením snímků dat Redis v zadaném intervalu a prahové hodnotě. interval je čas mezi exporty snímků a keysChangedThreshold je počet operací změn klíčů potřebných k aktivaci snímku. Další informace o perzistenci naleznete v dokumentaci: Redis perzistence.

Integrace hostování Garnet modeluje prostředek Garnet ve formě typu GarnetResource. Pro získání přístupu k tomuto typu a k rozhraním API, která vám umožní jej přidat do balíčku NuGet 📦Aspire.Hosting.Garnet v projektu hostitele aplikace .

dotnet add package Aspire.Hosting.Garnet

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidejte prostředek Garnet

V projektu hostitele aplikace zavolejte AddGarnet na instanci builder, abyste přidali zdroj Garnetu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí ghcr.io/microsoft/garnet, vytvoří na místním počítači novou instanci Garnetu. Odkaz na váš prostředek Garnet (proměnná cache) je přidán do ExampleProject.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "cache". Pro více informací se podívejte na životní cyklus zdrojů kontejneru.

Spropitné

Pokud byste se raději připojili k existující instanci Garnet, zavolejte místo toho AddConnectionString. Pro více informací viz Odkaz na stávající zdroje.

Přidání zdroje Garnet s datovým objemem

Pokud chcete přidat datový svazek do prostředku Garnet, zavolejte metodu AddGarnet prostředku 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...

Objem dat se používá k zachování dat Garnet mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data v kontejneru Garnet a pokud není zadaný parametr name, název se náhodně vygeneruje. Další informace o objemech dat a podrobnosti o tom, proč se upřednostňují před bind mounts, naleznete v dokumentaci Docker: Svazky.

Přidání prostředku Garnet s datovým bind mountem

Chcete-li přidat datové připojení k prostředku Garnet, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Bind mounty však umožňují přímý přístup a úpravy souborů na hostitelském systému, což je ideální pro průběžný vývoj a testování, kde jsou zapotřebí změny v reálném čase.

Připojení pro datová úložiště využívají systém souborů hostitelského počítače k uchování dat Garnet při restartování kontejneru. Připojení datového svazku je připojeno k cestě C:\Garnet\Data ve systému Windows (nebo /Garnet/Data na Unix) na hostitelském počítači v kontejneru Garnet. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidat prostředek Garnet s trvalým uložením

Pokud chcete do prostředku Garnet přidat trvalost, zavolejte metodu WithPersistence s připojením datového svazku nebo datové vazby:

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

Předchozí kód přidá trvalost do prostředku Redis pořízením snímků dat Garnetu v zadaném intervalu a prahové hodnotě. interval je čas mezi exporty snímků a keysChangedThreshold je počet operací změn klíčů potřebných k aktivaci snímku. Další informace o perzistenci naleznete v dokumentu Redis: Perzistence.

Integrační model hostování Valkey modeluje prostředek Valkey jako typ ValkeyResource. Přístup k tomuto typu a k rozhraním API, která umožňují jeho přidání do 📦Aspire.Hosting.Valkey balíčku NuGet v projektu hostitele aplikace .

dotnet add package Aspire.Hosting.Valkey

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidejte prostředek Valkey

V projektu hostitele aplikace zavolejte AddValkey na instanci builder pro přidání prostředku Valkey.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Když .NET.NET Aspire přidá do hostitele aplikace obraz kontejneru, jak je znázorněno v předchozím příkladu s obrazem docker.io/valkey/valkey, vytvoří na vašem místním počítači novou instanci Valkey. Do cachese přidá odkaz na prostředek Valkey (proměnná ExampleProject).

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "cache". Pro více informací se podívejte na životní cyklus zdrojů kontejneru.

Spropitné

Pokud se raději připojíte k existující instanci Valkey, zavolejte místo toho AddConnectionString. Pro více informací viz Odkaz na stávající zdroje.

Přidejte zdroj Valkey s datovým objemem

Pokud chcete k prostředku Valkey přidat datový svazek, zavolejte metodu AddValkey na prostředku 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...

Objem dat se používá k zachování dat Valkey mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data v kontejneru Valkey a pokud není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojení vazby, najdete v dokumentaci Docker: Svazky.

Přidání prostředku Valkey s připojením datového vazebního bodu

Chcete-li přidat datovou vazbu k prostředku Valkey, zavolejte metodu 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...

Důležitý

Data vazby mají omezenou funkčnost ve srovnání s volume, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je činí vhodnějšími pro produkční prostředí. Připojení vazeb však umožňuje přímý přístup a úpravy souborů v hostitelském systému, což je ideální pro vývoj a testování, kdy jsou potřebné změny v reálném čase.

Vazby datového připojení využívají systém souborů hostitelského počítače k uchování dat Valkey při restartování kontejneru. Datový úložný svazek je připojen na cestě C:\Valkey\Data v systému Windows (nebo /Valkey/Data ve Unix) na hostitelském počítači v kontejneru Valkey. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidat prostředek Valkey s persistencí

Pokud chcete do prostředku Valkey přidat trvalost, zavolejte metodu WithPersistence s připojením datového svazku nebo vazby dat:

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

Předchozí kód přidá trvalost do prostředku Redis pořízením snímků dat Valkey v zadaném intervalu a prahové hodnotě. interval je čas mezi exporty snímků a keysChangedThreshold je počet operací změn klíčů potřebných k aktivaci snímku. Další informace o perzistenci najdete v dokumentaci viz Redis: Perzistence.

Hostování kontrol stavu integrace

Integrace hostování Redis automaticky přidá kontrolu stavu pro příslušný typ prostředku. Kontrola stavu ověřuje, že je server spuštěný a že se k němu dá navázat připojení.

Integrační hostování spoléhá na 📦 AspNetCore.HealthChecks a balíček NuGetRedis.

integrace Client

Pokud chcete začít s .NET AspireRedis distribuovanou integrací ukládání do mezipaměti, nainstalujte 📦Aspire. StackExchange.Redis. DistributedCaching balíček NuGet v projektu využívajícím klienta, tj. projekt aplikace, která používá klienta Redis distribuované ukládání do mezipaměti. Integrace klienta Redis registruje instanci IDistributedCache, kterou můžete použít k interakci s Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Přidejte klienta Redis

V souboru Program.cs projektu, který využívá klienta, zavolejte rozšíření AddRedisDistributedCache a zaregistrujte požadované služby pro distribuované ukládání do mezipaměti a přidejte IDistributedCache pro použití prostřednictvím kontejneru injektáže závislostí.

builder.AddRedisDistributedCache(connectionName: "cache");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Redis do hostitelského projektu aplikace. Další informace naleznete v části Přidání Redis prostředků.

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Garnet do hostitelského projektu aplikace. Další informace najdete v části přidání prostředků Garnet.

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Valkey do hostitelského projektu aplikace. Další informace najdete v tématu Přidání prostředku Valkey.

Potom můžete načíst instanci IDistributedCache pomocí vkládání závislostí. Pokud například chcete načíst mezipaměť ze služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidejte klienta Redis s klíčem

Mohou nastat situace, kdy chcete registrovat více instancí IDistributedCache s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty Redis, zavolejte metodu AddKeyedRedisDistributedCache:

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

Potom můžete získat instance IDistributedCache pomocí dependency injection. Pokud například chcete načíst připojení z příkladové služby:

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

Další informace o službách s klíči najdete v části .NET injektáž závislostí: služby s klíči.

Konfigurace

Integrace .NET AspireRedis distribuované mezipaměti poskytuje několik možností konfigurace připojení Redis na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddRedisDistributedCachezadat název připojovacího řetězce:

builder.AddRedisDistributedCache("cache");

A pak se připojovací řetězec načte z oddílu konfigurace ConnectionStrings.

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

Další informace o formátování tohoto řetězce připojení najdete v konfigurační dokumentaci Stack Exchange Redis.

Použití zprostředkovatelů konfigurace

Integrace .NET Aspire Stack Exchange Redis pro distribuované ukládání do mezipaměti podporuje Microsoft.Extensions.Configuration. Načte StackExchangeRedisSettings z konfigurace pomocí klíče Aspire:StackExchange:Redis. Příklad appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma Redis distribuované integrace klienta pro ukládání do mezipaměti JSON naleznete v tématu Aspire. StackExchange.Redis. DistributedCaching/ConfigurationSchema.json.

Používejte vložené delegáty

Můžete také předat delegáta Action<StackExchangeRedisSettings> k nastavení některých nebo všech možností přímo, například ke konfiguraci DisableTracing.

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

Můžete také nastavit ConfigurationOptions pomocí parametru delegáta Action<ConfigurationOptions> configureOptions metody AddRedisDistributedCache. Pokud například chcete nastavit časový limit připojení:

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

Client testy stavu integrace

Ve výchozím nastavení mají .NET.NET Aspireklientské integracekontroly stavu povoleny pro všechny služby. Podobně mnoho .NET.NET Aspirehostovacích integrací také povoluje koncové body kontroly stavu. Další informace najdete tady:

Integrace distribuované mezipaměti .NET AspireRedis zpracovává následující:

  • Přidá kontrolu stavu, když je StackExchangeRedisSettings.DisableHealthChecksfalse, přičemž se pokusí připojit k instanci kontejneru.
  • Integruje se s HTTP koncovým bodem /health, který určuje, že všechny registrované kontroly stavu musí být úspěšně dokončeny, aby byla aplikace považována za připravenou přijímat síťový provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfiguraci protokolování, trasování a metrik, které jsou někdy označovány jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireRedis distribuovaného ukládání do mezipaměti používá následující logovací kategorie:

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

Trasování

Integrace .NET AspireRedis distribuované mezipaměti bude generovat následující aktivity trasování pomocí OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Měření

Integrace .NET AspireRedis pro distribuované ukládání mezipaměti v současné době nepodporuje metriky ve výchozím nastavení kvůli omezením knihovny StackExchange.Redis.

Viz také

*: Redis je registrovaná ochranná známka společnosti Redis Ltd. Všechna práva v nich jsou vyhrazena pro Redis Ltd. Jakékoli použití společností Microsoft je určené pouze pro referenční účely a nezoznačuje žádné sponzorství, doporučení ani přidružení mezi Redis a Microsoftem. Návrat na horní?