Condividi tramite

® integrazione della memorizzazione nella cache dell'output di .NET AspireRedis*

  • Articolo

include:integrazione dell'hosting e Client integrazione

Scopri come utilizzare l'integrazione della memorizzazione nella cache dell'output .NET AspireRedis. L'integrazione viene usata per registrare un provider di di memorizzazione nella cache dell'output supportato da un con l'immagine del contenitore .

Impara a usare l'integrazione della cache di output .NET AspireRedis. L'integrazione viene usata per registrare un provider di di memorizzazione nella cache dell'output supportato da un Garnet con l'immagine del contenitore .

Informazioni su come usare l'integrazione della memorizzazione nella cache dell'output .NET AspireRedis. L'integrazione viene usata per registrare un provider di di memorizzazione nella cache dell'output supportato da un Valkey con l'immagine del contenitore .

Integrazione dell'hosting

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

dotnet add package Aspire.Hosting.Redis

Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze del pacchetto nelle applicazioni .NET.

Aggiungere 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

Preferisci connetterti a un'istanza esistente di Redis? Chiama 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 container 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 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 container docker.io/rediscommander/redis-commander all'host dell'app che esegue l'app Commander.

Mancia

Per configurare la porta host per la catena di RedisCommanderResource, 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 la risorsa Redis con montaggio dati vincolati

Per aggiungere un montaggio di binding 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 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, consultare dotnet add package oppure Gestire le dipendenze dei pacchetti 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 ulteriori informazioni, vedere ciclo di vita delle risorse dei contenitori.

Suggerimento

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 ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi di associazione , consultare la documentazione Docker: 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 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 montaggi di associazione consentono l'accesso diretto e la modifica diretta dei file nel 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 montaggi di bind dei dati, vedere 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 ulteriori informazioni sulla persistenza, consultare i documenti Redis: 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 .

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 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 ulteriori informazioni, vedere il 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, ideali per lo sviluppo e il test in cui c'è bisogno di apportare 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 montaggio riassociato dei dati è montato su C:\Valkey\Data su Windows (o su /Valkey/Data nel percorso Unix) sulla macchina host nel contenitore Valkey. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: 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 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 di 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 .NET Aspire Stack Exchange Redis l'integrazione della memorizzazione nella cache di output client, installare il 📦Aspire. StackExchange.Redis. OutputCaching pacchetto NuGet nel progetto client-consume, ovvero il progetto per l'applicazione che usa la memorizzazione nella cache dell'output client.

dotnet add package Aspire.StackExchange.Redis.OutputCaching

Aggiungere la memorizzazione nella cache dell'output

Nel file Program.cs del tuo progetto client-consuming, chiamare su qualsiasi IHostApplicationBuilder il metodo di estensione AddRedisOutputCache per registrare i servizi necessari per la cache dell'output.

builder.AddRedisOutputCache(connectionName: "cache");

Suggerimento

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 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 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 RedisRedis stack di .NET Aspire 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": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Per lo schema completo Redisclient di integrazione JSON, vedere Aspire. StackExchange.Redis/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 il ConfigurationOptions di usando il parametro delegato del metodo . Ad esempio, per impostare il timeout della connessione:

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

Controlli della salute

Per impostazione predefinita, le integrazioni .NET.NET Aspire abilitano i controlli di stato per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

L'integrazione del caching dell'output di Stack Exchange .NET Aspire gestisce le seguenti operazioni di stack Redis:

  • Aggiunge il controllo integrità StackExchange.Redis, tenta di aprire la connessione e genera un'eccezione quando ha esito negativo.
  • 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.Redis
  • Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

Tracciamento

L'integrazione della memorizzazione nella cache dell'output Redis stack di .NET AspireRedis genera le attività di traccia seguenti 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.

integrazione di hosting AzureRedis

Per distribuire le risorse di Redis in Azure, installare il 📦Aspire.Hosting.Azure.Redispacchetto NuGet.

dotnet add package Aspire.Hosting.Azure.Redis

Aggiungere risorsa Azure Cache for Redisserver

Dopo aver installato il pacchetto di .NET Aspire hosting AzureRedis, chiama il metodo di estensione AddAzureRedis nel progetto host della tua app.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

La precedente chiamata a AddAzureRedis configura la risorsa Redisserver per essere distribuita come Azure Cache for Redis.

Importante

Per impostazione predefinita, AddAzureRedis configura l'autenticazione Microsoft Entra ID. Ciò richiede modifiche alle applicazioni che devono connettersi a queste risorse, ad esempio integrazioni client.

Aggiungere l'output Azure Cache for Redisclient

Per impostazione predefinita, quando si chiama AddAzureRedis nell'integrazione dell'hosting Redis, viene configurato il pacchetto NuGet 📦 Microsoft.Azure.StackExchangeRedis per abilitare l'autenticazione.

dotnet add package Microsoft.Azure.StackExchangeRedis

La connessione Redis può essere utilizzata attraverso l'integrazione client e Microsoft.Azure.StackExchangeRedis. Prendere in considerazione il codice di configurazione seguente:

var azureOptionsProvider = new AzureOptionsProvider();

var configurationOptions = ConfigurationOptions.Parse(
    builder.Configuration.GetConnectionString("cache") ?? 
    throw new InvalidOperationException("Could not find a 'cache' connection string."));

if (configurationOptions.EndPoints.Any(azureOptionsProvider.IsMatch))
{
    await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(
        new DefaultAzureCredential());
}

builder.AddRedisOutputCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

Per altre informazioni, vedere Microsoft.Azure. StackExchangeRedis repository.

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?