Ler em inglês

Compartilhar via


.NET Aspire Redis * Integração de cache distribuído ®

Escolher um recurso de hospedagem que dê suporte ao protocolo Redis

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

Saiba como usar a integração de cache distribuída .NET AspireRedis. A biblioteca de é usada para registrar um provedor de IDistributedCache apoiado por um servidor com a imagem de contêiner .

Saiba como usar a integração de cache distribuída .NET AspireRedis. A biblioteca de é usada para registrar um provedor de IDistributedCache apoiado por um servidor Garnet com a imagem de contêiner .

Saiba como usar a integração de cache distribuída .NET AspireRedis. A biblioteca de é usada para registrar um provedor de IDistributedCache apoiado por um servidor Valkey com a imagem de contêiner .

Integração de hospedagem

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

CLI do .NET
dotnet add package Aspire.Hosting.Redis

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

Adicionar Redis recurso

No projeto de host do aplicativo, chame AddRedis na instância builder para adicionar um recurso de Redis:

C#
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 o ciclo de vida do recurso 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 com Redis Insights

Para adicionar o Redis Insights ao recurso Redis, chame o método WithRedisInsight:

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

Observação

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

Adicionar o recurso Redis com o Commander Redis

Para adicionar o Redis Commander ao recurso Redis, chame o método WithRedisCommander:

C#
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 host para a cadeia RedisCommanderResource, faça uma chamada para a API 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:

C#
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 é utilizado para manter persistentes os dados de Redis fora do ciclo de vida de seu container. 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 preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar o recurso Redis com montagem de vínculo de dados

Para adicionar uma montagem de associação de dados ao recurso Redis, chame o método WithDataBindMount:

C#
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

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

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

Adicionar recurso Redis com persistência

Para adicionar persistência ao recurso Redis, chame o método WithPersistence utilizando o volume de dados ou o ponto de montagem de dados associado.

C#
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âneo e o keysChangedThreshold é o número de operações de alteração de chave necessárias para gerar 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 da Garnet como o tipo GarnetResource. Para acessar esse tipo e APIs que permitem adicioná-lo ao seu 📦Aspire. Hosting.Garnet pacote NuGet no projeto de host do aplicativo.

CLI do .NET
dotnet add package Aspire.Hosting.Garnet

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

Adicionar recurso garnet

No projeto de host do aplicativo, chame AddGarnet na instância builder para adicionar um recurso garnet:

C#
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 o ciclo de vida do recurso 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 um recurso Garnet com volume de dados

Para adicionar um volume de dados ao recurso garnet, chame o método AddGarnet no recurso garnet:

C#
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 aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar recurso Garnet com montagem vinculada de dados

Para adicionar uma montagem de associação de dados ao recurso garnet, chame o método WithDataBindMount:

C#
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

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

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

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

C#
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âneo e o keysChangedThreshold é o número de operações de alteração de chave necessárias para gerar 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 APIs que permitem adicioná-lo ao seu pacote NuGet 📦Aspire.Hosting.Valkey no projeto do host do aplicativo .

CLI do .NET
dotnet add package Aspire.Hosting.Valkey

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

Adicionar recurso do Valkey

No projeto de host do aplicativo, chame AddValkey na instância builder para adicionar um recurso valkey:

C#
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 o ciclo de vida do recurso 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 o recurso Valkey com volume de dados

Para adicionar um volume de dados ao recurso Valkey, chame o método AddValkey no recurso Valkey:

C#
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 do Valkey fora do ciclo de vida de seu 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 preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar o recurso Valkey com montagem vinculada a dados

Para adicionar uma montagem de associação de dados ao recurso Valkey, chame o método WithDataBindMount:

C#
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

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

Montagens de vinculação de dados dependem do sistema de arquivos do computador host para armazenar de forma persistente os dados do Valkey durante reinicializações de contêiner. A montagem de associação de dados é montada no C:\Valkey\Data no caminho do Windows (ou /Valkey/Data no Unix) no computador host no contêiner valkey. Para obter mais informações sobre montagens de vínculo, consulte a documentação Docker: Montagens de vínculo.

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 vinculação de dados:

C#
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âneo e o keysChangedThreshold é o número de operações de alteração de chave necessárias para gerar 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 saúde 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 de cache distribuído .NET AspireRedis, instale o pacote NuGet 📦Aspire.StackExchange.Redis.DistributedCaching no projeto cliente, ou seja, o projeto do aplicativo que usa o cliente de cache distribuído Redis. A integração do cliente Redis registra uma instância de IDistributedCache que você pode usar para interagir com Redis.

CLI do .NET
dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Adicionar Redis cliente

No arquivo Program.cs do projeto que consome o cliente, chame a extensão AddRedisDistributedCache para registrar os serviços necessários para cache distribuído, depois adicione um IDistributedCache para uso pelo contêiner de injeção de dependência.

C#
builder.AddRedisDistributedCache(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 o recursodo Adicionar .

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 mais informações, consulte Adicionar recurso Valkey.

Em seguida, você pode usar a injeção de dependência para recuperar a instância de IDistributedCache. Por exemplo, para recuperar o cache de um serviço:

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

Para mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente chaveado Redis

Pode haver situações em que você deseja registrar várias instâncias de IDistributedCache com nomes de conexão diferentes. Para registrar clientes Redis com chave, chame o método AddKeyedRedisDistributedCache:

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

Em seguida, você pode recuperar as instâncias de IDistributedCache usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre serviços com chave, consulte a seção .NET injeção de dependência: serviços com chave.

Configuração

A integração de cache distribuído .NET AspireRedis 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 builder.AddRedisDistributedCache:

C#
builder.AddRedisDistributedCache("cache");

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

JSON
{
  "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 distribuída do .NET Aspire Stack Exchange Redis dá suporte a Microsoft.Extensions.Configuration. O sistema carrega a StackExchangeRedisSettings da configuração usando a chave Aspire:StackExchange:Redis. Exemplo appsettings.json que configura algumas das opções:

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

Para obter o esquema completo de integração do cliente de cache distribuído RedisJSON, consulte Aspire. StackExchange.Redis. DistributedCaching/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<StackExchangeRedisSettings> para configurar algumas ou todas as opções diretamente, por exemplo, para configurar DisableTracing:

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

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

C#
builder.AddRedisDistributedCache(
    "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 distribuído .NET AspireRedis lida com o seguinte:

  • 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 integridade registradas devem passar para que o aplicativo seja considerado pronto para receber tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de 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 de Eventos

A integração de cache distribuída .NET AspireRedis usa as seguintes categorias de log:

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

Rastreamento

A integração de cache distribuído .NET AspireRedis emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

A integração de cache distribuído .NET AspireRedis atualmente não dá suporte automaticamente a métricas 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 pela Microsoft é apenas para fins referenciais e não indica nenhum patrocínio, endosso ou afiliação entre Redis e a Microsoft. Voltar ao topo?