Condividi tramite

® .NET AspireRedis* integrazione del caching distribuito

  • Articolo

Include: integrazione dell'hosting e Client integrazione

Informazioni su come usare l'integrazione della cache distribuita .NET AspireRedis. La libreria viene usata per registrare un provider di IDistributedCache supportato da un server con l'immagine del contenitore .

Informazioni su come usare l'integrazione della cache distribuita .NET AspireRedis. La libreria viene usata per registrare un provider di IDistributedCache supportato da un server Garnet con l'immagine del contenitore .

Informazioni su come usare l'integrazione della cache distribuita .NET AspireRedis. La libreria Aspire.StackExchange.Redis.DistributedCaching viene utilizzata per registrare un provider di IDistributedCache supportato da un server Valkey con l'immagine del contenitore docker.io/valkey/valkey.

Integrazione dell'hosting

L'integrazione di hosting Redis modella una risorsa Redis come tipo RedisResource. Per accedere a questo tipo e alle API per esprimerle come risorse nel progetto host dell'app, aggiungere il pacchetto NuGet 📦Aspire.Hosting.Redis.

dotnet add package Aspire.Hosting.Redis

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere la risorsa Redis

Nel progetto host dell'app, chiama AddRedis sull'istanza builder per aggiungere una risorsa Redis.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/Redis/Redis, crea una nuova istanza Redis nel computer locale. Viene aggiunto un riferimento alla risorsa Redis (la variabile cache) nel ExampleProject.

Il metodo WithReference configura una connessione nel ExampleProject denominato "cache". Per altre informazioni, vedere ciclo di vita delle risorse del contenitore.

Consiglio

Se preferisci connetterti a un'istanza di Redis esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere Redis risorsa con Redis Insights

Per aggiungere Redis Insights alla risorsa Redis, chiamare il metodo 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 è un'interfaccia grafica gratuita per l'analisi dei dati Redis in tutti i sistemi operativi e le distribuzioni di Redis con l'aiuto dell'assistente di intelligenza artificiale, Redis Copilot. .NET .NET Aspire aggiunge un'altra immagine del contenitore docker.io/redis/redisinsight all'host dell'app che esegue l'app comandante.

Nota

Per configurare la porta host per la catena di RedisInsightResource, è necessario effettuare una chiamata all'API WithHostPort e specificare il numero di porta desiderato.

Aggiungi la risorsa Redis con il Comandante Redis

Per aggiungere il Redis Comandante alla risorsa Redis, chiamare il metodo 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 è un'applicazione Web Node.js usata per visualizzare, modificare e gestire un database Redis. .NET .NET Aspire aggiunge un'altra immagine del contenitore docker.io/rediscommander/redis-commander all'host dell'app che esegue l'app comandante.

Consiglio

Per configurare la porta host per la catena di RedisCommanderResource, è necessario effettuare una chiamata all'API WithHostPort e specificare il numero di porta desiderato.

Aggiungere la risorsa Redis con volume di dati

Per aggiungere un volume di dati alla risorsa Redis, chiamare il metodo WithDataVolume nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati Redis all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data nel contenitore Redis e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere risorsa Redis con data bind mount

Per aggiungere un bind mount dei dati alla risorsa Redis, chiamare il metodo 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test quando sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere i dati Redis persistenti tra i riavvii dei container. Il bind mount dei dati viene montato su C:\Redis\Data su Windows (o /Redis/Data sul percorso di Unix) sulla macchina host nel contenitore Redis. Per ulteriori informazioni sui montaggi di bind dei dati, consultare i documenti Docker: Bind mounts.

Aggiungi la risorsa Redis con persistenza

Per aggiungere la persistenza alla risorsa Redis, chiamare il metodo WithPersistence con il volume di dati o il montaggio dell'associazione dati:

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

Il codice precedente aggiunge la persistenza alla risorsa Redis eseguendo snapshot dei dati Redis a un intervallo e una soglia specificati. Il interval è il tempo tra le esportazioni di snapshot e il keysChangedThreshold è il numero di operazioni di modifica della chiave necessarie per attivare uno snapshot. Per altre informazioni sulla persistenza, vedere la documentazione Redis: Persistenza.

L'integrazione di hosting di Garnet modella una risorsa Garnet come il tipo GarnetResource. Per accedere a questo tipo e API che consentono di aggiungerlo al . Hosting.Garnet pacchetto NuGet nel progetto host dell'app .

dotnet add package Aspire.Hosting.Garnet

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere una risorsa Garnet

Nel progetto host dell'app, chiama AddGarnet sull'istanza di builder per aggiungere una risorsa Garnet.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine ghcr.io/microsoft/garnet, crea una nuova istanza Garnet nel computer locale. Un riferimento alla risorsa Garnet (la variabile cache) viene aggiunto al ExampleProject.

Il metodo WithReference configura una connessione nel ExampleProject denominato "cache". Per altre informazioni, vedere ciclo di vita delle risorse del contenitore.

Consiglio

Se invece si preferisce connettersi a un'istanza garnet esistente, chiamare AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere una risorsa Garnet con un volume di dati

Per aggiungere un volume di dati alla risorsa Garnet, chiamare il metodo AddGarnet nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati Garnet all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data nel contenitore Garnet e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere una risorsa Garnet con bind mount dei dati

Per aggiungere un montaggio di associazione dati alla risorsa Garnet, chiamare il metodo 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test quando sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Garnet tra i riavvii del contenitore. Il mount di associazione dati viene montato nel percorso C:\Garnet\Data su Windows (o nel percorso /Garnet/Data su Unix) sul computer host nel contenitore Garnet. Per ulteriori informazioni sui montaggi di bind dei dati, consultare i documenti Docker: Bind mounts.

Aggiungere una risorsa Garnet con persistenza

Per aggiungere la persistenza alla risorsa Garnet, chiamare il metodo WithPersistence con il volume di dati o il montaggio dell'associazione dati:

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

Il codice precedente aggiunge la persistenza alla risorsa Redis eseguendo snapshot dei dati Garnet a un intervallo e una soglia specificati. Il interval è il tempo tra le esportazioni di snapshot e il keysChangedThreshold è il numero di operazioni di modifica della chiave necessarie per attivare uno snapshot. Per altre informazioni sulla persistenza, vedere la documentazione Redis: Persistenza.

L'integrazione di hosting di Valkey modella una risorsa Valkey come tipo ValkeyResource. Per accedere a questo tipo e alle API che consentono di aggiungerlo al 📦Aspire.Hosting.Valkey pacchetto NuGet nel progetto host dell'app .

dotnet add package Aspire.Hosting.Valkey

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere una risorsa Valkey

Nel progetto host dell'app chiamare AddValkey nell'istanza di builder per aggiungere una risorsa Valkey:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come mostrato nell'esempio precedente con l'immagine docker.io/valkey/valkey, viene creata una nuova istanza Valkey sul tuo computer locale. Un riferimento alla risorsa Valkey (la variabile cache) viene aggiunto al ExampleProject.

Il metodo WithReference configura una connessione nel ExampleProject denominato "cache". Per altre informazioni, vedere ciclo di vita delle risorse del contenitore.

Consiglio

Se invece si preferisce connettersi a un'istanza valkey esistente, chiamare AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere una risorsa Valkey con un volume di dati

Per aggiungere un volume di dati alla risorsa Valkey, chiamare il metodo AddValkey nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati Valkey all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data nel contenitore Valkey e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere una risorsa Valkey con il montaggio dell'associazione dati

Per aggiungere un montaggio di associazione dati alla risorsa Valkey, chiamare il metodo 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test quando sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Valkey tra i riavvii del contenitore. Il bind mount dei dati è montato su C:\Valkey\Data su Windows (o su /Valkey/Data nel percorso Unix) sul computer host nel container Valkey. Per ulteriori informazioni sui montaggi di bind dei dati, consultare i documenti Docker: Bind mounts.

Aggiungere una risorsa Valkey con persistenza

Per aggiungere la persistenza alla risorsa Valkey, chiamare il metodo WithPersistence con il volume di dati o il bind mount dei dati.

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

Il codice precedente aggiunge la persistenza alla risorsa Redis eseguendo snapshot dei dati Valkey a un intervallo e una soglia specificati. Il interval è il tempo tra le esportazioni di snapshot e il keysChangedThreshold è il numero di operazioni di modifica della chiave necessarie per attivare uno snapshot. Per altre informazioni sulla persistenza, vedere la documentazione Redis: Persistenza.

Hosting dei controlli di integrità dell'integrazione

L'integrazione dell'hosting Redis aggiunge automaticamente una verifica di integrità per il tipo di risorsa appropriato. Il controllo integrità verifica che il server sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul 📦 AspNetCore.HealthChecks.Redis pacchetto NuGet.

integrazione Client

Per iniziare a usare l'integrazione della cache distribuita .NET AspireRedis, installare il pacchetto NuGet 📦Aspire.StackExchange.Redis.DistributedCaching nel progetto che utilizza il client, ovvero il progetto per l'applicazione che utilizza il client cache distribuita Redis. L'integrazione client Redis registra un'istanza di IDistributedCache che è possibile usare per interagire con Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Aggiungere Redis client

Nel file Program.cs del progetto cliente-consumatore, chiamata l'estensione AddRedisDistributedCache per registrare i servizi necessari per la memorizzazione nella cache distribuita e aggiungere un IDistributedCache per l'utilizzo tramite il contenitore di iniezione delle dipendenze.

builder.AddRedisDistributedCache(connectionName: "cache");

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Redis nel progetto host dell'app. Per altre informazioni, vedere Aggiungere Redis risorsa.

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Garnet nel progetto host dell'app. Per altre informazioni, vedere Aggiungere una risorsa Garnet.

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Valkey nel progetto host dell'app. Per altre informazioni, vedere Aggiungere risorsa Valkey.

È quindi possibile recuperare l'istanza di IDistributedCache usando l'iniezione delle dipendenze. Ad esempio, per recuperare la cache da un servizio:

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

Per altre informazioni sull'iniezione delle dipendenze, vedere .NET 'iniezione delle dipendenze.

Aggiungere un client Redis con chiave incorporata

In alcuni casi potrebbe essere necessario registrare più istanze di IDistributedCache con nomi di connessione diversi. Per registrare i client Redis con chiave, chiamare il metodo AddKeyedRedisDistributedCache:

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

È quindi possibile recuperare le istanze di IDistributedCache tramite l'iniezione di dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione della memorizzazione nella cache distribuita .NET AspireRedis offre più opzioni per configurare la connessione Redis in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddRedisDistributedCache:

builder.AddRedisDistributedCache("cache");

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Per ulteriori informazioni su come formattare questa stringa di connessione, consultare i documenti di configurazione di Stack Exchange Redis.

Usare i provider di configurazione

L'integrazione della memorizzazione nella cache distribuita .NET Aspire Stack Exchange Redis supporta Microsoft.Extensions.Configuration. Carica il StackExchangeRedisSettings dalla configurazione usando la chiave Aspire:StackExchange:Redis. Esempio appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo Redis di integrazione del client di memorizzazione distribuita JSON, vedere Aspire.StackExchange.Redis.DistributedCaching/ConfigurationSchema.json.

Utilizzare delegati in linea

È anche possibile passare il delegato Action<StackExchangeRedisSettings> per configurare alcune o tutte le opzioni inline, ad esempio per configurare DisableTracing:

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

È anche possibile configurare il ConfigurationOptions di usando il parametro delegato del metodo . Ad esempio, per impostare il timeout della connessione:

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

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

L'integrazione della memorizzazione nella cache distribuita .NET AspireRedis gestisce le operazioni seguenti:

  • Aggiunge il controllo di integrità quando StackExchangeRedisSettings.DisableHealthChecks è false, che tenta di connettersi all'istanza del contenitore.
  • Si integra con l'endpoint HTTP /health, il quale specifica che tutti i controlli di integrità registrati devono essere superati con successo affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente la registrazione, il tracciamento e le metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione della memorizzazione nella cache distribuita .NET AspireRedis usa le categorie di log seguenti:

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

Tracciatura

L'integrazione della memorizzazione nella cache distribuita .NET AspireRedis genererà le attività di tracciamento seguenti usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Metriche

L'integrazione della memorizzazione nella cache distribuita .NET AspireRedis attualmente non supporta le metriche di default a causa di limitazioni con la libreria StackExchange.Redis.

Vedere anche

*: Redis è un marchio registrato di Redis Ltd. Tutti i diritti in esso contenuti sono riservati a Redis Ltd. Qualsiasi utilizzo da parte di Microsoft è solo a scopo referenziale e non indica alcuna sponsorizzazione, approvazione o affiliazione tra Redis e Microsoft. Tornare all'superiore?