® integrazione della memorizzazione nella cache dell'output di .NET AspireRedis*
include integrazione dell'hosting
e integrazione di Client
Scopri come usare l'integrazione della cache di output .NET AspireRedis. L'integrazione del client Aspire.StackExchange.Redis.OutputCaching viene utilizzata per registrare un provider di ASP.NET Core Output Caching supportato da un server Redis con l'immagine del contenitore docker.io/library/redis.
Scopri come utilizzare l'integrazione della memorizzazione nella cache dell'output con .NET AspireRedis. L'integrazione del client Aspire.StackExchange.Redis.OutputCaching viene utilizzata per registrare un provider di memorizzazione nella cache di output ASP.NET Core supportato da un server Garnet con l'immagine del contenitore ghcr.io/microsoft/garnet.
Scopri come utilizzare l'integrazione della memorizzazione dell'output nella cache .NET AspireRedis. L'integrazione del client Aspire.StackExchange.Redis.OutputCaching viene utilizzata per registrare un provider di memorizzazione nella cache dell'output ASP.NET Core, supportato da un server Valkey insieme all'immagine del contenitore docker.io/valkey/valkey.
Integrazione dell'hosting
L'integrazione di hosting con 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 ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze del pacchetto nelle applicazioni .NET.
Aggiungi la risorsa Redis
Nel progetto host dell'app chiamare AddRedis nell'istanza di 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. Un riferimento alla risorsa Redis (la variabile cache) viene aggiunto a 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 esistente di Redis, utilizza invece AddConnectionString. Per altre informazioni, vedere Consultare le risorse esistenti.
Aggiungere Redis risorsa con Redis Insights
Per aggiungere il Redis Insights alla risorsa di 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 Commander.
Nota
Per configurare la porta host per la catena di RedisInsightResource è necessaria una chiamata all'API WithHostPort e specificare il numero di porta desiderato.
Aggiungere la risorsa Redis con Redis Commander
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 commander.
Consiglio
Per configurare la porta host per la catena di RedisCommanderResource è necessaria 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 ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai bind mounts, consultare la documentazione Docker: Volumi.
Aggiungere la risorsa Redis con mount di tipo bind per dati
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 bind mount dei dati hanno funzionalità limitate rispetto ai volumi, che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.
I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Redis tra i riavvii del contenitore. Il data bind mount viene montato al percorso C:\Redis\Data su Windows (o /Redis/Data nel percorso Unix) sulla macchina host nel contenitore Redis. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.
Aggiungere la risorsa Redis con persistenza
Per aggiungere la persistenza alla risorsa Redis, chiamare il metodo WithPersistence con un volume di dati o un bind mount di 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 Redis docs: Persistenza.
L'integrazione di hosting Garnet modella una risorsa Garnet come il tipo GarnetResource. Per accedere a questo tipo e alle API che consentono di aggiungerlo al pacchetto NuGet 📦Aspire.Hosting.Garnet nel progetto host dell'app.
dotnet add package Aspire.Hosting.Garnet
Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze del pacchetto nelle applicazioni .NET.
Aggiungere una risorsa Garnet
Nel progetto host dell'app, chiama AddGarnet sull'istanza 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 sul 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 Consultare le 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 ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai bind mount, consultare la Docker documentazione: Volumi.
Aggiungere una risorsa Garnet con il mount di associazione 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 'bind mounts' dei dati hanno funzionalità limitate rispetto ai volumi, che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il test in cui 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 montaggio dell'associazione dati viene montato nel C:\Garnet\Data in Windows (o /Garnet/Data in Unix) percorso nel computer host nel contenitore Garnet. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.
Aggiungi 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 Redis docs: Persistenza.
L'integrazione di hosting Valkey rappresenta una risorsa Valkey come tipo ValkeyResource. Per accedere a questo tipo e alle API che consentono di aggiungerlo al pacchetto NuGet 📦Aspire.Hosting.Valkey nel progetto host dell'app .
- .NET CLI
- PackageReference
dotnet add package Aspire.Hosting.Valkey
Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze del pacchetto nelle applicazioni .NET.
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 di container all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/valkey/valkey, crea una nuova istanza Valkey nel 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 preferisci connetterti a un'istanza Valkey esistente, chiama AddConnectionString. Per altre informazioni, vedere Consultare le 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 ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai bind mount, consultare 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 mount point di dati hanno funzionalità limitate rispetto ai volumi, che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il test in cui 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 in Windows (o su /Valkey/Data nel percorso Unix) sulla macchina host nel contenitore Valkey. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.
Aggiungi 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 Redis docs: Persistenza.
Verifiche di integrità dell'integrazione per l'hosting
L'integrazione dell'hosting Redis aggiunge automaticamente un controllo 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 pacchetto NuGet 📦 AspNetCore.HealthChecks.Redis.
integrazione Client
Per iniziare a usare l'integrazione del client di memorizzazione nella cache dell'output di .NET Aspire Stack Exchange Redis, installare il pacchetto NuGet 📦Aspire.StackExchange.Redis.OutputCaching nel progetto che consuma il client, cioè, il progetto dell'applicazione che utilizza il client di memorizzazione nella cache dell'output. L'integrazione del client di caching dell'output Redis registra i servizi necessari per abilitare le chiamate ai metodi CacheOutput e l'utilizzo dell'attributo [OutputCache] per fare affidamento su Redis come meccanismo di caching.
dotnet add package Aspire.StackExchange.Redis.OutputCaching
Aggiungere la memorizzazione nella cache dell'output
Nel file Program.cs del progetto che utilizza il client chiamare il metodo di estensione AddRedisOutputCache in qualsiasi IHostApplicationBuilder per registrare i servizi necessari per la memorizzazione nella cache dell'output.
builder.AddRedisOutputCache(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.
Suggerimento
Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Valkey nel progetto host dell'app. Per ulteriori informazioni, vedere Aggiungi risorsa Valkey.
Aggiungere il middleware alla pipeline di elaborazione delle richieste chiamando UseOutputCache(IApplicationBuilder):
var app = builder.Build();
app.UseOutputCache();
Per app per le API minime, configurare un endpoint per eseguire la memorizzazione nella cache chiamando CacheOutputo applicando il OutputCacheAttribute, come illustrato negli esempi seguenti:
app.MapGet("/cached", () => "Hello world!")
.CacheOutput();
app.MapGet(
"/attribute",
[OutputCache] () => "Hello world!");
Per le app con controller, applicare l'attributo [OutputCache] al metodo di azione. Per le app Razor Pages, applicare l'attributo alla classe di pagine Razor.
Configurazione
L'integrazione della memorizzazione nella cache dell'output .NET Aspire Stack Exchange Redis offre più opzioni per configurare la connessione Redis in base ai requisiti e alle convenzioni del tuo 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 AddRedisOutputCache:
builder.AddRedisOutputCache(connectionName: "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 la documentazione sulla configurazione di Stack Exchange Redis.
Usare i provider di configurazione
L'integrazione della memorizzazione nella cache dell'output di .NET Aspire Stack Exchange Redis supporta Microsoft.Extensions.Configuration. Carica il StackExchangeRedisSettings dalla configurazione utilizzando 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 di integrazione del client per la memorizzazione nella cache dell'output, vedere Aspire.StackExchange.Redis.OutputCaching/ConfigurationSchema.json.
Usare delegati inline
È inoltre possibile passare il delegato Action<StackExchangeRedisSettings> configurationSettings per configurare alcune o tutte le opzioni direttamente nel codice, ad esempio per disabilitare i controlli di integrità nel codice:
builder.AddRedisOutputCache(
"cache",
static settings => settings.DisableHealthChecks = true);
È anche possibile configurare le ConfigurationOptions utilizzando il parametro delegato Action<ConfigurationOptions> configureOptions del metodo AddRedisOutputCache. Ad esempio, per impostare il timeout della connessione:
builder.AddRedisOutputCache(
"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:
- controlli di integrità dell'app .NET in C#
- controlli dello stato di salute in ASP.NET Core
L'integrazione del caching dell'output .NET Aspire di Stack Exchange Redis gestisce quanto segue:
- Aggiunge il controllo di integrità quando StackExchangeRedisSettings.DisableHealthChecks è
false, tentando di connettersi all'istanza del contenitore. - Si integra con l'endpoint HTTP
/health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.
Osservabilità e telemetria
.NET
.NET Aspire le integrazioni impostano automaticamente la registrazione, la tracciatura e le metriche, talvolta noti 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 dell'output caching di .NET Aspire Stack Exchange Redis utilizza le seguenti categorie di log:
Aspire.StackExchange.RedisMicrosoft.AspNetCore.OutputCaching.StackExchangeRedis
Tracciamento
L'integrazione della cache di output di .NET Aspire Stack Exchange Redis emetterà le seguenti attività di tracciamento usando OpenTelemetry:
OpenTelemetry.Instrumentation.StackExchangeRedis
Metriche
L'integrazione dell'output caching di .NET Aspire Stack Exchange Redis attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni della 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?
