Partilhar via

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

  • Artigo

Inclui: Integração de alojamento e integração de Client

Saiba como usar a integração de cache distribuído .NET AspireRedis. A biblioteca Aspire.StackExchange.Redis.DistributedCaching é utilizada para registar um fornecedor IDistributedCache suportado por um servidor Redis com a imagem de container docker.io/library/redis.

Saiba como usar a integração de cache distribuído .NET AspireRedis. A biblioteca Aspire.StackExchange.Redis.DistributedCaching é usada para registar um provedor IDistributedCache apoiado por um servidor Garnet com a imagem de contentor ghcr.io/microsoft/garnet.

Saiba como usar a integração de cache distribuído .NET AspireRedis. A biblioteca de Aspire.StackExchange.Redis.DistributedCaching é usada para registar um provedor de IDistributedCache apoiado por um servidor Valkey com a imagem de contentor docker.io/valkey/valkey.

Integração de hospedagem

A integração de hospedagem Redis modela um recurso Redis como o tipo RedisResource. Para aceder a este tipo e às APIs para expressá-los como recursos no projeto de aplicação anfitriã , adicione o pacote NuGet 📦Aspire.Hosting.Redis.

dotnet add package Aspire.Hosting.Redis

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

Adicionar Redis recurso

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

O método WithReference configura uma conexão no ExampleProject chamado "cache". Para obter mais informações, consulte Ciclo de vida do recurso de 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 Fazer referência a recursos existentes.

Adicionar recursos Redis com Redis Insights

Para adicionar o 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 de Redis em todos os sistemas operacionais e implantações de Redis com a ajuda de nosso assistente de IA, Redis Copilot. .NET .NET Aspire adiciona outra imagem de contentor docker.io/redis/redisinsight ao host da aplicação que executa o commander.

Observação

Para configurar a porta do host para o RedisInsightResource encadeie uma chamada para a API do 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 visualizar, editar e gerenciar um banco de dados Redis. .NET .NET Aspire adiciona mais uma imagem de container ao host da aplicação que executa a aplicação commander.

Dica

Para configurar a porta do host para o RedisCommanderResource encadeie uma chamada para a API do 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 manter os dados 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 relação a montagens vinculadas , consulte a documentação Docker: Volumes.

Adicionar Redis recurso com montagem de associação de dados

Para adicionar uma montagem de ligaçã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

As montagens vinculadas de dados 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 bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes 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 Redis nas reinicializações do contêiner. A montagem de associação de dados é montada 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 vinculação de dados, consulte Docker Docs: Bind mounts.

Adicionar um 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 associaçã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 snapshot e o keysChangedThreshold é o número de operações de alteração de chave necessárias para disparar um snapshot. Para obter mais informações sobre persistência, consulte Redis docs: Persistence.

A integração de hospedagem Garnet modela um recurso Garnet como o tipo GarnetResource. Para aceder a este tipo e às APIs que permitem adicioná-lo ao seu pacote NuGet 📦Aspire.Hosting.Garnet no projeto do host de aplicação .

dotnet add package Aspire.Hosting.Garnet

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

Adicionar recurso Garnet

Em seu projeto de host de 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, como mostrado no exemplo anterior com a imagem ghcr.io/microsoft/garnet, ele cria uma nova instância Garnet em sua máquina local. Uma referência ao seu recurso Garnet (a variável cache) é adicionada ao ExampleProject.

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

Dica

Se você preferir se conectar a uma instância Garnet existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a 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 manter os dados 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 preferidos em relação a montagens vinculadas , consulte a documentação Docker: Volumes.

Adicionar recurso Garnet com montagem de ligação de dados

Para adicionar uma montagem de ligação de dados 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

Os bind mounts de dados têm funcionalidade limitada em comparação com os volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes 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 persistir os dados Garnet nas reinicializações do contêiner. A montagem da associação de dados é montada no caminho C:\Garnet\Data no Windows (ou /Garnet/Data no Unix) na máquina host no contêiner Garnet. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

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 associação 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 Garnet em um intervalo e limite especificados. O interval é o tempo entre as exportações de snapshot e o keysChangedThreshold é o número de operações de alteração de chave necessárias para disparar um snapshot. Para obter mais informações sobre persistência, consulte Redis docs: Persistence.

A integração de hospedagem Valkey modela um recurso Valkey como o tipo ValkeyResource. Para aceder a este tipo e às APIs que lhe permitem adicioná-lo ao pacote NuGet 📦Aspire.Hosting.Valkey no projeto da aplicação host.

dotnet add package Aspire.Hosting.Valkey

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

Adicionar recurso Valkey

Em seu projeto de host de 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, como mostrado no exemplo anterior com a imagem docker.io/valkey/valkey, ele cria uma nova instância do Valkey em sua máquina local. Uma referência ao seu recurso Valkey (a variável cache) é adicionada ao ExampleProject.

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

Dica

Se você preferir se conectar a uma instância existente do Valkey, chame AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a 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 manter os dados 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 mais informações sobre volumes de dados e sobre a razão pela qual são preferidos em relação a montagens vinculadas, consulte a documentação: Volumes.

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

Para adicionar uma montagem de ligaçã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

Os suportes de ligação de de dados 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 bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes 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 Valkey nas reinicializações do contêiner. A montagem de dados ocorre no caminho C:\Valkey\Data no Windows (ou /Valkey/Data no Unix) na máquina anfitriã no contentor Valkey. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Adicionar um 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 associação 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 snapshot e o keysChangedThreshold é o número de operações de alteração de chave necessárias para disparar um snapshot. Para obter mais informações sobre persistência, consulte Redis docs: Persistence.

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.

Client integração

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 para o aplicativo que usa o cliente de cache distribuído Redis. A integração do cliente Redis registra uma instância IDistributedCache que você pode usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Adicionar Redis cliente

No ficheiro Program.cs do projeto consumidor de cliente, chame a extensão AddRedisDistributedCache para registar os serviços necessários para cache distribuído e adicione um IDistributedCache para utilização através do contentor de injeção de dependência.

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 Adicionar Redis recurso.

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Garnet no projeto 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 recurso Valkey.

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

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

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

Adicionar cliente Redis com chave

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

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

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

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

Para mais informações sobre serviços com chave, veja .NET injeção de dependência: Serviços com chave.

Configuração

A .NET AspireRedis integração de cache distribuído oferece várias opções para configurar a conexão Redis com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

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

builder.AddRedisDistributedCache("cache");

E, 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 Redis do Stack Exchange.

Usar provedores de configuração

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

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

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

Usar delegados em linha

Você também pode passar a delegação de Action<StackExchangeRedisSettings> para configurar algumas ou todas as opções em linha, por exemplo, para configurar DisableTracing:

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

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

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

Client verificações de saúde de integração

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

A integração de cache distribuída .NET AspireRedis trata do seguinte:

  • Adiciona a verificação de integridade quando StackExchangeRedisSettings.DisableHealthChecks é false, que tenta se conectar à instância do contêiner.
  • Integra-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção de configuração.

Registo

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

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

Rastreio

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

Atualmente, a integração de cache distribuído do .NET AspireRedis não oferece suporte a métricas por padrão devido a limitações com a biblioteca StackExchange.Redis.

Ver também

*: Redis é uma marca registada de Redis Ltd. Quaisquer direitos são reservados à Redis Ltd. Qualquer uso pela Microsoft é apenas para fins referenciais e não indica qualquer patrocínio, endosso ou afiliação entre a Redis e a Microsoft. Voltar ao topo?