Compartilhar via

.NET Aspire Redisintegração de cache de saída®*

  • Artigo

Inclui: integração de hospedagem e Client integração

Saiba como usar a integração de cache de saída .NET AspireRedis. A integração do cliente Aspire.StackExchange.Redis.OutputCaching é usada para registrar um provedor de cache de saída ASP.NET Core apoiado por um servidor Redis com a imagem de contêiner docker.io/library/redis.

Saiba como usar a integração de cache de saída .NET AspireRedis. A integração do Aspire.StackExchange.Redis.OutputCaching cliente é usada para registrar um ASP.NET Core provedor de Cache de Saída apoiado por um servidor Garnet com a ghcr.io/microsoft/garnet imagem de contêiner.

Saiba como usar a integração de cache de saída .NET AspireRedis. A integração do Aspire.StackExchange.Redis.OutputCaching cliente é usada para registrar um provedor de ASP.NET Core cache de saída apoiado por um servidor Valkey com a imagem de contêiner docker.io/valkey/valkey.

Integração de hospedagem

A integração de hospedagem de Redis modela o recurso Redis como tipo RedisResource. Para acessar esse tipo e as APIs para expressá-las como recursos em seu projeto de hospedagem de app , adicione o pacote NuGet 📦Aspire.Hosting.Redis:

dotnet add package Aspire.Hosting.Redis

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar Redis recurso

No projeto de host do aplicativo, chame AddRedis na instância builder para adicionar um recurso de 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 adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem docker.io/Redis/Redis, ele cria uma nova instância de Redis em seu computador local. Uma referência ao recurso Redis (a variável cache) é adicionada ao ExampleProject.

O método WithReference configura uma conexão no ExampleProject denominado "cache". Para obter mais informações, consulte ciclo de vida do recurso do contêiner.

Dica

Se você preferir se conectar a uma instância de Redis existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso Redis ao Redis Insights

Para adicionar os Redis Insights ao recurso Redis, chame o método 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 é uma interface gráfica gratuita para analisar dados Redis em todos os sistemas operacionais e implantações de Redis com a ajuda do nosso assistente de IA, Redis Copilot. .NET .NET Aspire adiciona outra imagem de contêiner docker.io/redis/redisinsight ao host do aplicativo que executa o aplicativo comandante.

Nota

Para configurar a porta do host para RedisInsightResource, faça uma chamada à API de WithHostPort e forneça o número de porta desejado.

Adicionar recurso Redis com o comandante Redis

Para adicionar o Redis Commander ao recurso Redis, chame o método 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 é um aplicativo Web Node.js usado para exibir, editar e gerenciar um banco de dados Redis. .NET .NET Aspire adiciona outra imagem de contêiner docker.io/rediscommander/redis-commander ao host do aplicativo que executa o aplicativo comandante.

Dica

Para configurar a porta do host para RedisCommanderResource, faça uma chamada à API de WithHostPort e forneça o número de porta desejado.

Adicionar o recurso Redis com volume de dados

Para adicionar um volume de dados ao recurso Redis, chame o método WithDataVolume no recurso 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...

O volume de dados é usado para persistir os dados de Redis fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data no contêiner Redis e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de mounts de associação, consulte a documentação em Docker: Volumes.

Adicionar recurso Redis com vinculação de dados

Para adicionar uma montagem de associação de dados ao recurso Redis, chame o método 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

Montagens de ligação de dados têm funcionalidade limitada em comparação com volumes , os quais oferecem melhor desempenho, portabilidade e segurança, o que os torna mais adequados para ambientes de produção. No entanto, as bind mounts permitem acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e testes em que são necessárias alterações em tempo real.

As montagens de vínculo de dados dependem do sistema de arquivos da máquina host para preservar os dados Redis entre reinicializações de contêiner. A vinculação de dados é montada no caminho C:\Redis\Data no Windows (ou /Redis/Data no Unix) no computador host dentro do contêiner Redis. Para obter mais informações sobre montagens de ligação de dados, consulte a documentação: montagens de ligação.

Adicionar o recurso Redis com persistência

Para adicionar persistência ao recurso Redis, chame o método WithPersistence com o volume de dados ou a montagem de vinculação de dados.

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

O código anterior adiciona persistência ao recurso Redis tirando instantâneos dos dados Redis em um intervalo e limite especificados. O interval é o tempo entre as exportações de instantâneos e o keysChangedThreshold é o número de operações de alteração de chave necessárias para acionar um instantâneo. Para obter mais informações sobre persistência, consulte Redis documentos: Persistência.

A integração de hospedagem da Garnet modela um recurso Garnet como o tipo GarnetResource. Para acessar este tipo e as APIs que permitem adicioná-lo ao pacote NuGet 📦Aspire.Hosting.Garnet no projeto host do aplicativo.

dotnet add package Aspire.Hosting.Garnet

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar recurso garnet

No projeto de host do aplicativo, chame AddGarnet na instância builder para adicionar um recurso 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 adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem ghcr.io/microsoft/garnet, ele cria uma nova instância garnet em seu computador local. Uma referência ao recurso garnet (a variável cache) é adicionada ao ExampleProject.

O método WithReference configura uma conexão no ExampleProject denominado "cache". Para obter mais informações, consulte ciclo de vida do recurso do contêiner.

Dica

Se você preferir se conectar a uma instância da Garnet existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso Garnet com volume de dados

Para adicionar um volume de dados ao recurso garnet, chame o método AddGarnet no recurso 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...

O volume de dados é usado para persistir os dados da Garnet fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data no contêiner Garnet e, quando um parâmetro name não é fornecido, o nome é gerado de forma aleatória. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de montagens bind, consulte a Docker documentação: Volumes.

Adicionar recurso garnet com a montagem de associação de dados

Para adicionar um data bind mount ao recurso Garnet, chame o método 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

Montagens de ligação de dados têm funcionalidade limitada em comparação com volumes , os quais oferecem melhor desempenho, portabilidade e segurança, o que os torna mais adequados para ambientes de produção. No entanto, as bind mounts permitem acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e testes em que são necessárias alterações em tempo real.

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados do Garnet durante as reinicializações de contêiner. A montagem de dados é feita no caminho C:\Garnet\Data no Windows (ou /Garnet/Data no Unix) no computador host, dentro do contêiner Garnet. Para obter mais informações sobre montagens de bind de dados, consulte Docker na documentação: montagens de bind.

Adicionar recurso Garnet com persistência

Para adicionar persistência ao recurso garnet, chame o método WithPersistence com o volume de dados ou a montagem de vínculo de dados.

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

O código anterior adiciona persistência ao recurso Redis tirando instantâneos dos dados da Garnet em um intervalo e limite especificados. O interval é o tempo entre as exportações de instantâneos e o keysChangedThreshold é o número de operações de alteração de chave necessárias para acionar um instantâneo. Para obter mais informações sobre persistência, consulte Redis documentos: Persistência.

A integração de hospedagem Valkey modela um recurso Valkey como o tipo ValkeyResource. Para acessar esse tipo e as APIs que permitem adicioná-lo ao seu pacote NuGet 📦Aspire.Hosting.Valkey no projeto do host do aplicativo .

dotnet add package Aspire.Hosting.Valkey

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar recurso do Valkey

No projeto de host do aplicativo, chame AddValkey na instância builder para adicionar um recurso 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 adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem docker.io/valkey/valkey, ele cria uma nova instância do Valkey em seu computador local. Uma referência ao recurso Valkey (a variável cache) é adicionada ao ExampleProject.

O método WithReference configura uma conexão no ExampleProject denominado "cache". Para obter mais informações, consulte ciclo de vida do recurso do contêiner.

Dica

Se você preferir se conectar a uma instância do Valkey existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso Valkey com volume de dados

Para adicionar um volume de dados ao recurso Valkey, chame o método AddValkey no recurso 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...

O volume de dados é usado para persistir os dados "Valkey" independentemente do ciclo de vida do contêiner. O volume de dados é montado no caminho /data no contêiner Valkey e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de montagens de ligação, consulte a Docker documentação: Volumes.

Adicionar o recurso Valkey com montagem de vinculação de dados

Para adicionar uma montagem de associação de dados ao recurso Valkey, chame o método 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

Montagens de ligação de dados têm funcionalidade limitada em comparação com volumes , os quais oferecem melhor desempenho, portabilidade e segurança, o que os torna mais adequados para ambientes de produção. No entanto, as bind mounts permitem acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e testes em que são necessárias alterações em tempo real.

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados do Valkey nas reinicializações de contêiner. A montagem de ligação de dados é montada no caminho C:\Valkey\Data no Windows (ou /Valkey/Data em Unix) na máquina host no contêiner Valkey. Para obter mais informações sobre montagens de bind de dados, consulte Docker na documentação: montagens de bind.

Adicionar recurso Valkey com persistência

Para adicionar persistência ao recurso Valkey, chame o método WithPersistence com o volume de dados ou a montagem de vínculo de dados.

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

O código anterior adiciona persistência ao recurso Redis tirando instantâneos dos dados valkey em um intervalo e limite especificados. O interval é o tempo entre as exportações de instantâneos e o keysChangedThreshold é o número de operações de alteração de chave necessárias para acionar um instantâneo. Para obter mais informações sobre persistência, consulte Redis documentos: Persistência.

Verificações de integridade da integração de hospedagem

A integração de hospedagem Redis adiciona automaticamente uma verificação de integridade para o tipo de recurso apropriado. A verificação de integridade verifica se o servidor está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do 📦 AspNetCore.HealthChecks.Redis pacote NuGet.

integração Client

Para começar a usar a integração do cliente de cache de saída da .NET Aspire Stack Exchange Redis, instale o pacote NuGet 📦Aspire.StackExchange.Redis.OutputCaching no projeto que utiliza o cliente de cache, ou seja, o projeto da aplicação que utiliza o cliente de cache de saída. A integração do cliente para cache de saída Redis registra serviços necessários para habilitar chamadas de método CacheOutput e o uso do atributo [OutputCache] para usar Redis como mecanismo de cache.

dotnet add package Aspire.StackExchange.Redis.OutputCaching

Adicionar cache de saída

No arquivo Program.cs do projeto consumidor do cliente, chame o método de extensão AddRedisOutputCache em qualquer IHostApplicationBuilder para registrar os serviços necessários para o cache de saída.

builder.AddRedisOutputCache(connectionName: "cache");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Redis no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar recursoRedis.

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Garnet no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar recurso garnet.

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Valkey no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar o recurso Valkey.

Adicione o middleware ao pipeline de processamento de solicitação chamando UseOutputCache(IApplicationBuilder):

var app = builder.Build();

app.UseOutputCache();

Para aplicativos mínimos de API, configure um endpoint para realizar o cache chamando CacheOutputou aplicando o OutputCacheAttribute, conforme mostrado nos seguintes exemplos:

app.MapGet("/cached", () => "Hello world!")
   .CacheOutput();

app.MapGet(
    "/attribute",
    [OutputCache] () => "Hello world!");

Para aplicativos com controladores, aplique o atributo [OutputCache] ao método de ação. Para aplicativos Razor Pages, aplique o atributo à classe de página Razor.

Configuração

A integração de cache de saída do .NET Aspire Stack Exchange Redis fornece várias opções para configurar a conexão Redis com base nos requisitos e convenções do seu projeto.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar AddRedisOutputCache:

builder.AddRedisOutputCache(connectionName: "cache");

Em seguida, a cadeia de conexão será recuperada da seção de configuração ConnectionStrings:

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

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte os documentos de configuração do Stack Exchange Redis.

Usar provedores de configuração

A integração de cache de saída do .NET Aspire Stack Exchange Redis dá suporte a Microsoft.Extensions.Configuration. Ele carrega a StackExchangeRedisSettings da configuração usando a chave Aspire:StackExchange:Redis. Exemplo appsettings.json que configura algumas das opções:

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

Para obter o esquema Redis de integração completa do cliente de cache de saída JSON, consulte Aspire. StackExchange.Redis. OutputCaching/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<StackExchangeRedisSettings> configurationSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desabilitar verificações de saúde usando código:

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.DisableHealthChecks  = true);

Você também pode configurar o ConfigurationOptions usando o parâmetro delegado Action<ConfigurationOptions> configureOptions do método AddRedisOutputCache. Por exemplo, para definir o tempo limite da conexão:

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

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

A integração de cache de saída do .NET Aspire Stack Exchange Redis gerencia os seguintes aspectos:

  • Adiciona a verificação de integridade quando StackExchangeRedisSettings.DisableHealthChecks é false, que tenta conectar-se à instância do contêiner.
  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de saúde registradas devem ser aprovadas para que o aplicativo seja considerado pronto para receber tráfego.

Observabilidade e telemetria

As integrações .NET.NET Aspire configuram automaticamente log, rastreamento e métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração de cache de saída do .NET Aspire Stack Exchange Redis usa as seguintes categorias de log:

  • Aspire.StackExchange.Redis
  • Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

Rastreamento

A integração de cache de saída do .NET Aspire Stack Exchange Redis emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

A integração de cache de saída do .NET Aspire Stack Exchange Redis atualmente não dá suporte a métricas por padrão devido a limitações com a biblioteca StackExchange.Redis.

Consulte também

*: Redis é uma marca registrada da Redis Ltd. Todos os direitos reservados à Redis Ltd. Qualquer uso da Microsoft é apenas para fins referenciais e não indica nenhum patrocínio, endosso ou afiliação entre Redis e a Microsoft. Retornar àsuperior?