Partilhar 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ído .NET AspireRedis. A biblioteca é usada para registrar um provedor IDistributedCache de , apoiado por um com a imagem de contêiner .

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

Saiba como usar a integração de cache distribuído .NET AspireRedis. A biblioteca é usada para registar um provedor de IDistributedCache de apoiado por um Valkey com a imagem de conteiner .

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 que lhe permitem adicioná-lo ao seu 📦Aspire.Hosting.Redis pacote NuGet no projeto de aplicação host .

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 outro docker.io/redis/redisinsight de imagem de contêiner ao host do aplicativo que executa o aplicativo 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 outra imagem de contêiner docker.io/rediscommander/redis-commander ao host da aplicação que executa o aplicativo commander.

Dica

Para configurar a porta do host para o RedisCommanderResource, encadeie uma chamada à API WithHostPort. Em seguida, 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

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 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 associaçã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 esse tipo e as APIs que permitem adicioná-lo ao seu 📦Aspire.Hosting.Garnet pacote NuGet no projeto de aplicação de hospedagem .

dotnet add package Aspire.Hosting.Garnet

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

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 de ligação , consulte Docker docs: 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 suportes de ligação de dados têm funcionalidades limitadas 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 APIs que lhe permitem adicioná-lo ao seu 📦Aspire. Hosting.Valkey pacote NuGet no aplicativo host projeto.

dotnet add package Aspire.Hosting.Valkey

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

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 obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em relação a montagens de bind , consulte os documentos Docker: Volumes.

Adicionar recurso Valkey com montagem de ligaçã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 da associação de dados é montada no caminho C:\Valkey\Data no Windows (ou /Valkey/Data no Unix) na máquina host no contêiner 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 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.

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 consumidor client, ou seja, o projeto para o aplicativo que usa o cache distribuído Redisclient.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Adicionar Redisclient

No arquivo de Program.cs do seu projeto que consome client, chame a extensão AddRedisDistributedCache para registar os serviços necessários para caching distribuído e adicione um IDistributedCache para uso através do contentor de injeção de dependências.

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 Redisclient 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 do .NET Aspire Stack Exchange Redis suporta 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": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Para o esquema completo de integração de RedisclientJSON, consulte Aspire.StackExchange.Redis/ConfigurationSchema.json.

Usar delegados embutidos

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);

Controlos sanitários

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral das 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 lança quando ela falha.
  • Integra-se com o 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 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 do .NET AspireRedis Distributed Caching usa as seguintes categorias de Log:

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

Rastreio

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

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

Azure Redis integração de hospedagem

Para implantar os seus recursos de Redis no 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 seu projeto de hospedagem da aplicação:

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 implementado como um Azure Cache for Redis.

Importante

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

Adicionar Azure Cache for Redisclient distribuído

Por padrão, quando chamar AddAzureRedis na sua integração de hospedagem Redis, ele configura o pacote NuGet 📦 da Microsoft.AzureStackExchangeRedis para permitir a autenticação.

dotnet add package Microsoft.Azure.StackExchangeRedis

A ligação Redis pode ser utilizada através da 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. StackExchangeRedis repositório.

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?