Compartilhar via

.NET Aspire Redis®* integração

  • Artigo

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 que permitem adicioná-lo ao seu 📦AspireHospedagemRedis pacote NuGet no projeto 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 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.

Nota

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, realizar uma chamada à API WithHostPort e fornecer 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 preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar o recurso Redis com montagem com 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

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

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados Redis entre reinicializações de contêiner. 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 disparar 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 .NET applications.

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 o ciclo de vida do recurso do 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 de amarração, consulte a documentação Docker: Volumes.

Adicionar recurso Garnet com montagem de vínculo 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 de bind permitem acesso direto e modificação de arquivos no sistema host, sendo ideal 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 do computador host para persistir os dados da Garnet nas reinicializações de contêiner. A montagem da associação de dados é montada no caminho C:\Garnet\Data no Windows (ou /Garnet/Data no Unix) no computador host no contêiner garnet. Para mais informações sobre montagens vinculadas de dados, consulte Docker docs: Montagens vinculadas.

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âneos e o keysChangedThreshold é o número de operações de alteração de chave necessárias para gerar um instantâneo. Para obter mais informações sobre persistência, consulte Redis documentos: Persistência.

A integração de hospedagem Valkey modela um recurso Valkey como o tipo ValkeyResource. Para acessar esse tipo e APIs que permitem adicioná-lo ao seu 📦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 .NET aplicativos.

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 o ciclo de vida do recurso do 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 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 , consulte a documentação Docker: Volumes.

Adicionar o recurso Valkey com a montagem de associação 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

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 vinculação permitem acesso direto e modificação de arquivos no sistema host, o que é ideal para desenvolvimento e testes nos quais são necessárias alterações em tempo real.

As montagens de vínculo de dados dependem do sistema de arquivos do computador host para manter persistentes os dados do Valkey nas reinicializações de contêiner. A montagem de associação de dados é montada no caminho C:\Valkey\Data no Windows (ou /Valkey/Data no Unix) no computador host no contêiner Valkey. Para obter mais informações sobre montagens bind de dados, consulte a documentação Docker: Bind mounts.

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 representa o tempo entre as exportações de instantâneos e o keysChangedThreshold é o número de operações de alteração de chave necessárias para acionar um instantâneo. Para obter mais informações sobre persistência, consulte Redis documentos: Persistência.

Verificações de integridade em integração 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 server está em execução e se é possível estabelecer uma conexão 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 .NET Aspire Stack Exchange Redisclient, instale o 📦Aspire. StackExchange.Redis pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o Redisclient. A integração Redisclient registra uma instância de IConnectionMultiplexer que você pode usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis

Adicionar Redisclient

No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddRedisClient em qualquer IHostApplicationBuilder para registrar um IConnectionMultiplexer por meio do container de injeção de dependências. 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 Redisde recursos.

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 Redisclient com chave

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 utilizar a injeção de dependência para recuperar as instâncias de IConnectionMultiplexer. 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 .NET Aspire Stack Exchange Redisclient fornece 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 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 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 em linha

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

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

Client verificações de integridade de integração

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 de integrações.

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

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.

Azure Redis integração de hospedagem

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

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 host 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 a autenticação Microsoft Entra ID . Isso requer alterações em aplicações que precisam se conectar a esses recursos, por exemplo, integrações client.

Adicionar Azure Cache for Redisclient

Por padrão, quando você chama AddAzureRedis em 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.AddRedisClient("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 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?