Compartilhar via

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

  • Artigo

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

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

Saiba como usar a integração de cache distribuída .NET AspireRedis. A biblioteca Aspire.StackExchange.Redis.DistributedCaching é usada para registrar um provedor de IDistributedCache apoiado por um Garnetserver com a imagem de contêiner ghcr.io/microsoft/garnet.

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 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 as APIs que permitem adicioná-lo ao seu pacote NuGet de 📦Aspire.Hosting.Redis no projeto de host do aplicativo .

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:

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:

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

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 a cadeia RedisCommanderResource, faça uma chamada à 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:

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:

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.

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.

dotnet add package Aspire.Hosting.Garnet

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

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 contêiner.

Dica

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

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:

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:

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 bind permitem acesso direto e modificação de arquivos no sistema host, sendo ideais para desenvolvimento e teste, onde são necessárias alterações em tempo real.

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 de dados, consulte a documentação de 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.

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 mudança 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 .

dotnet add package Aspire.Hosting.Valkey

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

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 contêiner de recurso.

Dica

Se você preferir se conectar a uma instância do Valkey existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referência de 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:

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 preferidos em vez de bind mounts, consulte os documentos de Docker: 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:

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 vinculadas permitem o acesso direto e a modificação de arquivos no sistema host, sendo ideal para desenvolvimento e teste quando as 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 ligação de dados, consulte Docker documentação: Montagens de ligação.

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:

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 exportações de instantâneos, e o keysChangedThreshold representa o número de operações de mudança de chave necessárias para disparar 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 saúde verifica se o server 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 📦Aspire.StackExchange.Redis.DistributedCaching pacote NuGet no projeto consumidor client, ou seja, o projeto do aplicativo que usa o cache distribuído Redisclient.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Adicionar Redisclient

No arquivo Program.cs do seu projeto de consumo de client, chame a extensão AddRedisDistributedCache para registrar os serviços necessários para cache distribuído e adicione um IDistributedCache para uso através do contêiner 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 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:

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

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

Acrescentar Redisclient como chave

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:

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:

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:

builder.AddRedisDistributedCache("cache");

Em seguida, a cadeia de conexão será recuperada da seção de configuração do 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 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:

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Para obter o esquema JSON de integração Redisclient completo, consulte Aspire. StackExchange.Redis/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:

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:

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

Verificações de saúde

Por padrão, as integrações .NET.NET Aspire ativam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

A integração de cache distribuído .NET AspireRedis lida com o seguinte:

  • Adiciona a verificação de integridade StackExchange.Redis, tenta abrir a conexão e gera quando ela falha.
  • Integra-se ao ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo seja considerado pronto para aceitar o 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ído .NET AspireRedis usa as seguintes categorias de Log:

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

Rastreamento

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

Atualmente, a integração da distribuição de cache .NET AspireRedis não suporta métricas por padrão devido a limitações com a biblioteca StackExchange.Redis.

Azure Redis integração de hospedagem

Para implantar seus recursos de Redis em Azure, instale o pacote NuGet 📦Aspire.Hosting.Azure.Redis:

dotnet add package Aspire.Hosting.Azure.Redis

Adicionar Azure Cache for Redisserver recurso

Depois de instalar o pacote de hospedagem .NET AspireAzureRedis, chame o método de extensão AddAzureRedis no projeto de hospedagem do aplicativo:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

A chamada anterior para AddAzureRedis configura o recurso Redisserver para ser implantado como um Azure Cache for Redis.

Importante

Por padrão, AddAzureRedis configura autenticação do Microsoft Entra ID. Isso requer alterações em aplicativos que precisam se conectar a esses recursos, por exemplo, client integrações.

Adicionar Azure Cache for Redis distribuído client

Por padrão, quando você chama AddAzureRedis na sua integração de hospedagem Redis, ele configura o pacote NuGet 📦 Microsoft.Azure. StackExchangeRedis para habilitar a autenticação:

dotnet add package Microsoft.Azure.StackExchangeRedis

A conexão Redis pode ser consumida usando a integração client e Microsoft.Azure.StackExchangeRedis. Considere o seguinte código de configuração:

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.AddRedisDistributedCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

Para obter mais informações, consulte o Microsoft.Azure. Repositório StackExchangeRedis.

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?