.NET Aspire Redis®* integração de cache de saída
Inclui:
integração de hospedagem e integração Client
Saiba como usar a integração de cache de saída .NET AspireRedis. A integração Aspire.StackExchange.Redis.OutputCachingclient é usada para registrar um provedor de cache de saída ASP.NET Core apoiado por um Redisserver com a imagem de contentor docker.io/library/redis.
Saiba como usar a integração de cache de saída .NET AspireRedis. A integração
Saiba como usar a integração de cache de saída .NET AspireRedis. A integração
Integração de hospedagem
A integração de hospedagem Redis modela um recurso Redis como o tipo RedisResource. Para aceder a este tipo e APIs que lhe permitem adicioná-lo ao seu 📦Aspire. Hospedagem.Redis pacote NuGet no aplicativo host projeto.
- .NET CLI
- PackageReference
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 Consulte os recursos existentes.
Adicionar Redis recurso com o 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 outra imagem de contentor docker.io/redis/redisinsight ao host da aplicação que executa 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 o 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 outro contentor de imagem docker.io/rediscommander/redis-commander ao anfitrião da aplicação que executa o Commander.
Dica
Para configurar a porta do host para o RedisCommanderResource encadeie uma chamada para a API do 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 por que eles são preferidos em relação a montagens de ligação bind , 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 ligação de dados dependem do sistema de arquivos da máquina host para persistir os dados Redis durante os rearranques do contêiner. A montagem de vínculo de dados é instalada no caminho C:\Redis\Data no Windows (ou /Redis/Data no Unix) na máquina anfitriã no contentor Redis. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: 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 na aplicação hospedeiro do projeto.
- .NET CLI
- PackageReference
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
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
As montagens de ligação de dados têm funcionalidade limitada em comparação com os volumes , que oferecem melhor desempenho, portabilidade e segurança, tornando os volumes 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 ficheiros da máquina anfitriã para manter os dados Garnet ao longo das reinicializações dos contêineres. 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 na aplicação anfitriã do projeto .
- .NET CLI
- PackageReference
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 pontos de ligação , consulte a documentação 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 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 pacote NuGet 📦 AspNetCore.HealthChecks.Redis.
Client Integração
Para começar a usar a integração de cache de saída do .NET Aspire Stack Exchange Redisclient, instale o pacote NuGet 📦Aspire.StackExchange.Redis.OutputCaching no projeto de consumo client, ou seja, o projeto do aplicativo que utiliza o cache de saída client.
- .NET CLI
- PackageReference
dotnet add package Aspire.StackExchange.Redis.OutputCaching
Adicionar cache de saída
No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddRedisOutputCache em qualquer IHostApplicationBuilder para registar os serviços necessários para cache de saída.
builder.AddRedisOutputCache(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.
Adicione o middleware ao pipeline de processamento de solicitações chamando UseOutputCache(IApplicationBuilder):
var app = builder.Build();
app.UseOutputCache();
Para aplicações de API mínimas, configure um ponto de extremidade para realizar caching chamando CacheOutputou aplicando o OutputCacheAttribute, conforme mostrado nos exemplos a seguir.
app.MapGet("/cached", () => "Hello world!")
.CacheOutput();
app.MapGet(
"/attribute",
[OutputCache] () => "Hello world!");
Para aplicativos com controladores, aplique o atributo [OutputCache] ao método action. Para aplicações Razor Pages, aplique o atributo à classe Razor Page.
Configuração
A integração de cache de saída Redis 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 string 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 AddRedisOutputCache:
builder.AddRedisOutputCache(connectionName: "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 esta 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 suporta Microsoft.Extensions.Configuration. Ele carrega o StackExchangeRedisSettings a partir 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, veja Aspire. StackExchange.Redis/ConfigurationSchema.json.
Usar delegados em linha
Você também pode passar o delegado Action<StackExchangeRedisSettings> configurationSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desativar verificações de integridade via código:
builder.AddRedisOutputCache(
"cache",
static settings => settings.DisableHealthChecks = true);
Você também pode configurar o ConfigurationOptions usando o parâmetro Action<ConfigurationOptions> configureOptions delegate do método AddRedisOutputCache. Por exemplo, para definir o tempo limite de conexão:
builder.AddRedisOutputCache(
"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 de saída do .NET Aspire Stack Exchange Redis 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 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 as configurações de Registo, Rastreio e Métricas, 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 podem também ser desativados utilizando as técnicas apresentadas na secção de configuração .
Registo
A integração de cache de saída do .NET Aspire Stack Exchange Redis usa as seguintes categorias de log:
Aspire.StackExchange.RedisMicrosoft.AspNetCore.OutputCaching.StackExchangeRedis
Rastreio
A integração de cache de saída do .NET Aspire Stack Exchange Redis emitirá as seguintes atividades de rastreamento usando OpenTelemetry:
OpenTelemetry.Instrumentation.StackExchangeRedis
Métricas
A integração de cache de saída do .NET Aspire Stack Exchange Redis atualmente 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 seus recursos de Redis no Azure, instale o 📦Aspire. Hospedagem.Azure.Redis pacote NuGet:
- .NET CLI
- PackageReference
dotnet add package Aspire.Hosting.Azure.Redis
Adicionar Azure Cache for Redisserver recurso
Após instalar o pacote de hospedagem .NET AspireAzureRedis, chame o método de extensão AddAzureRedis no projeto de hospedagem da sua 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 implantado como Azure Cache for Redis.
Importante
Por padrão, AddAzureRedis configura autenticação de ID do Microsoft Entra. Isso requer alterações em aplicações que precisam ligar-se a esses recursos, como por exemplo, client integrações.
Adicionar saída Azure Cache for Redisclient
Por padrão, quando se chama AddAzureRedis na integração de hospedagem Redis, ele configura 📦 Microsoft.Azure. o pacote NuGet StackExchangeRedis para habilitar a autenticação.
- .NET CLI
- PackageReference
dotnet add package Microsoft.Azure.StackExchangeRedis
A conexão Redis pode ser consumida usando a integração client e o 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.AddRedisOutputCache("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?
