Ler em inglês

Compartilhar via

.NET Aspire Redis®* integração

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

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

Redis é a plataforma de dados mais rápida do mundo para cache, pesquisa de vetores e bancos de dados NoSQL. A integração .NET AspireRedis permite que você se conecte a instâncias de Redis existentes ou crie novas instâncias de .NET com a imagem de contêiner docker.io/library/redis.

Garnet é um repositório de cache de alto desempenho da Microsoft Research e está em conformidade com o protocolo de serialização Redis (RESP). A integração .NET AspireRedis permite que você se conecte a instâncias existentes da Garnet ou crie novas instâncias de .NET com a imagem de contêiner ghcr.io/microsoft/garnet.

Valkey é um fork Redis e está em conformidade com o protocolo de serialização Redis (RESP). É um armazenamento de dados chave/valor de alto desempenho que dá suporte a uma variedade de cargas de trabalho, como cache, filas de mensagens e pode atuar como um banco de dados primário. A integração .NET AspireRedis permite que você se conecte a instâncias existentes do Valkey ou crie novas instâncias de .NET com a imagem de contêiner docker.io/valkey/valkey.

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:

dotnet add package Aspire.Hosting.Redis

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicações .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 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 Redis recurso utilizando Redis Insights

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

Observação

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

Adicionar Redis recurso com Redis Commander

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 armazenar os dados de Redis independentemente do ciclo de vida do contêiner. O volume de dados é montado no caminho /data no contêiner Redis e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de montagens bind, consulte a Docker documentação: Volumes.

Adicionar o recurso Redis com montagem por ligação de dados

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataBindMount(
                       source: @"C:\Redis\Data",
                       isReadOnly: false);

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

// After adding all resources, run the app...

Importante

As montagens bind 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, ideal para desenvolvimento e teste, quando são necessárias mudanças em tempo real.

As montagens de dados vinculados dependem do sistema de arquivos do computador host para persistir os dados Redis entre reinicializações dos contêineres. O ponto de montagem de dados é montado no caminho C:\Redis\Data no Windows (ou /Redis/Data no Unix) no computador host dentro do contêiner Redis. Para obter mais informações sobre montagens de vinculação de dados, consulte a documentação em Docker: Montagens de vinculação.

Adicionar recurso Redis com persistência

Para adicionar persistência ao recurso Redis, chame o método WithPersistence usando o volume de dados ou a montagem de vínculo de dados:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

// After adding all resources, run the app...

O código anterior adiciona persistência ao recurso Redis tirando instantâneos dos dados Redis em um intervalo e limite especificados. O interval é o tempo entre as exportações de instantâneo, 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 da Garnet modela um recurso Garnet como o tipo GarnetResource. Para acessar esse tipo e as APIs que permitem que você adicione isto ao seu pacote NuGet 📦Aspire.Hosting.Garnet no projeto de hospedagem 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 obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso Garnet com volume de dados

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume(isReadOnly: false);

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

// After adding all resources, run the app...

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

Adicionar recurso Garnet com montagem de vínculo de dados

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

As montagens bind 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, ideal para desenvolvimento e teste, quando são necessárias mudanças em tempo real.

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

Adicionar recurso Garnet com persistência

Para adicionar persistência ao recurso Garnet, chame o método WithPersistence com o volume de dados ou o ponto de 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 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 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 📦Aspire. Hosting.Valkey pacote NuGet 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 aplicações .NET.

Adicionar recurso do Valkey

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache");

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

// After adding all resources, run the app...

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem docker.io/valkey/valkey, ele cria uma nova instância do Valkey em seu computador local. Uma referência ao recurso Valkey (a variável cache) é adicionada ao ExampleProject.

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

Dica

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

Adicionar recurso Valkey com volume de dados

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

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume(isReadOnly: false);

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

// After adding all resources, run the app...

O volume de dados é usado para persistir os dados Valkey fora do ciclo de vida do 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 montagens bind, consulte a Docker documentação: Volumes.

Adicionar o recurso Valkey com montagem vinculada de dados

Para adicionar uma vinculaçã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

As montagens bind 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, ideal para desenvolvimento e teste, quando são necessárias mudanças em tempo real.

As montagens de vínculo de dados dependem do sistema de arquivos da máquina host para persistir os dados do Valkey nas reinicializações de contêiner. A montagem de vínculo de dados está 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 vinculação de dados, consulte a documentação em Docker: Montagens de vinculaçã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 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 instantâneo, 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.

Verificações de integridade das integrações de hospedagem

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

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

integração Client

Para começar a usar a integração do cliente .NET Aspire Stack Exchange Redis, instale o pacote NuGet 📦Aspire.StackExchange.Redis no projeto que consome o cliente, ou seja, o projeto do aplicativo que utiliza o cliente Redis. A integração do cliente Redis registra uma instância IConnectionMultiplexer que você pode usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis

Adicionar Redis cliente

No arquivo Program.cs do projeto cliente, chame o método de extensão AddRedisClient em qualquer IHostApplicationBuilder para registrar um IConnectionMultiplexer para uso através do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddRedisClient(connectionName: "cache");

Dica

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

Dica

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

Dica

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

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

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

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

Adicionar cliente com chave Redis

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

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

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

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

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

Configuração

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

Usar uma string de conexão

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

builder.AddRedis("cache");

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

builder.AddGarnet("cache");

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

builder.AddValkey("cache");

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

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

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

Usar provedores de configuração

A integração do .NET Aspire Stack Exchange Redis dá suporte a Microsoft.Extensions.Configuration. Carrega o StackExchangeRedisSettings da configuração utilizando a chave Aspire:StackExchange:Redis. Exemplo appsettings.json que configura algumas das opções:

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

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

Usar delegados em linha

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

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

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

Por padrão, .NET.NET Aspireintegrações com clientes 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 Stack Exchange .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 disponível para receber tráfego.

Observabilidade e telemetria

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

Registro

A integração .NET Aspire Stack Exchange Redis usa as seguintes categorias de log:

  • Aspire.StackExchange.Redis

Rastreamento

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

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

Consulte também

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