Partilhar via


.NET Aspire Redis®* integração

Inclui: de integraçãoHosting e integração

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

Garnet é um armazenamento de cache de alto desempenho da Microsoft Research e está em conformidade com o de protocolo de serialização (RESP). A integração .NET AspireRedis permite que você se conecte a instâncias Garnet existentes ou crie novas instâncias a partir 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 de chave/valor de alto desempenho que suporta 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 a partir 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 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 host da aplicação .

dotnet add package Aspire.Hosting.Redis

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

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 Redis recurso usando Redis Insights

Para adicionar o do Insights ao recurso , chame o método :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisInsight();

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

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

Redis Insights é uma interface gráfica gratuita para analisar dados de Redis em todos os sistemas operacionais e implantações de Redis com a ajuda de nosso assistente de IA, Redis Copilot. .NET .NET Aspire adiciona outra imagem de contentor docker.io/redis/redisinsight ao host da aplicação que executa a aplicação commander.

Observação

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

Adicionar recurso Redis com 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 outro docker.io/rediscommander/redis-commander de imagem de contêiner ao host do aplicativo que executa o aplicativo commander.

Dica

Para configurar a porta do host para o RedisCommanderResource, efetue uma chamada para a API WithHostPort e forneça o número de porta desejado.

Adicionar 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 as razões pelas quais eles são preferidos em relação às montagens de vinculação , ver Docker docs: Volumes.

Adicionar recurso Redis com montagem de ligaçã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 ligação de dados, consulte a documentação em Docker: Bind mounts.

Adicionar o recurso Redis com persistência

Para adicionar persistência ao recurso Redis, chame o método WithPersistence com o volume de dados ou a montagem de associação de dados:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

O código anterior adiciona persistência ao recurso Redis tirando instantâneos dos dados Redis em um intervalo e limite especificados. O interval é o tempo entre as exportações de snapshot e o keysChangedThreshold é o número de operações de alteração de chave necessárias para disparar um snapshot. Para obter mais informações sobre persistência, consulte Redis docs: Persistence.

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

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 motivos sobre por que eles são preferidos a montagens de ligação , consulte a documentação Docker: Volumes.

Adicionar recurso Garnet com ponto de 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

As montagens de ligação de dados têm funcionalidade limitada em comparação com volumes , que oferecem melhor desempenho, portabilidade e segurança, o que os torna 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 ligação de dados dependem do sistema de arquivos da máquina anfitriã para manter os dados do 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 mais informações sobre Data Bind Mounts, consulte a documentação em Docker: 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 adicionar pacote 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 ligação , consulte Docker docs: 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 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 estado 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 pacote AspNetCore.HealthChecks do 📦 e do pacote NuGet doRedis.

Client integração

Para começar com a integração do .NET Aspire Stack Exchange Redisclient, instale o pacote NuGet 📦Aspire.StackExchange.Redis no projeto que consome client, ou seja, o projeto para o aplicativo que usa o Redisclient. A integração Redisclient regista uma instância de IConnectionMultiplexer que tu podes usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis

Adicionar Redisclient

No arquivo de Program.cs do seu projeto que consome client, chame o método de extensão AddRedisClient em qualquer IHostApplicationBuilder para registrar um IConnectionMultiplexer para utilização 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 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 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 a 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 IConnectionMultiplexer com nomes de conexão diferentes. Para registrar clientes Redis chaveados, chame o método AddKeyedRedisClient:

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

Em seguida, podes conseguir recuperar as instâncias IConnectionMultiplexer utilizando a 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 a injeção de dependência .NET: Serviços com chave.

Configuração

A integração do Redisclient do .NET Aspire Stack Exchange 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 de 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 de 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 de 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 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 obter o esquema de integração completa RedisclientJSON, consulte Aspire.StackExchange.Redis/ConfigurationSchema.json.

Usar delegados embutidos

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

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

Client verificações de integridade da 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 das integrações.

A integração do .NET Aspire Stack Exchange Redis lida com o seguinte:

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

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente os registos, rastreio e métricas, que às vezes são conhecidos 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. As funcionalidades de telemetria também podem ser desativadas usando as técnicas apresentadas na secção de Configuração .

Registo

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

  • Aspire.StackExchange.Redis

Rastreio

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

Atualmente, a integração .NET Aspire Stack Exchange Redis não suporta, por padrão, métricas 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 host de 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 implementado como um Azure Cache for Redis.

Importante

Por padrão, AddAzureRedis configura autenticação do Microsoft Entra ID. Isso requer alterações em aplicações que precisam conectar-se 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 📦 Microsoft.Azure. O StackExchangeRedis pacote NuGet 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. 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?