Partilhar via

.NET Aspire Azure Cache for Redis® integração*

  • Artigo

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

Azure Cache for Redis fornece um armazenamento de dados na memória com base no software Redis. Redis melhora o desempenho e a escalabilidade de um aplicativo que usa fortemente armazenamentos de dados de back-end. Ele é capaz de processar grandes volumes de solicitações de aplicativos mantendo dados acessados com frequência na memória do servidor, que podem ser gravados e lidos rapidamente. Redis traz uma solução crítica de armazenamento de dados de baixa latência e alta taxa de transferência para aplicativos modernos.

Azure Cache for Redis oferece tanto o Redis de código aberto (OSS Redis) quanto um produto comercial da Redis Inc. (Redis Enterprise) como um serviço gerido. Ele fornece instâncias de servidor Redis seguras e dedicadas e total compatibilidade com API de Redis. A Microsoft opera o serviço, hospedado em Azuree utilizável por qualquer aplicativo dentro ou fora Azure.

A integração .NET AspireAzure Cache for Redis permite que você se conecte a instâncias de Azure Cache for Redis existentes, crie novas instâncias ou execute como um contêiner localmente a partir de .NET com a imagem de contêiner docker.io/library/redis.

Integração de hospedagem

A integração de hospedagem .NET AspireAzure Cache for Redis modela um recurso AzureRedis como o tipo AzureRedisCacheResource. Para aceder a este tipo de APIs e expressá-las como recursos no projeto do anfitrião da aplicação , adicione o pacote NuGet 📦Aspire.Hosting.Azure.Redis:

dotnet add package Aspire.Hosting.Azure.Redis

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

Adicionar AzureAzure Cache for Redis recurso

Em seu projeto de host de aplicativo, chame AddAzureRedis na instância builder para adicionar um recurso de AzureAzure Cache for Redis, conforme mostrado no exemplo a seguir:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache");

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

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

A chamada anterior para AddAzureRedis configura o recurso do servidor Redis para ser implementado como um Azure Cache for Redis.

Importante

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

Dica

Quando você chama AddAzureRedis, ele chama implicitamente AddAzureProvisioning—que adiciona suporte para gerar recursos de Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Provisionamento gerado Bicep

Se você é novo no Bicep, é uma linguagem específica do domínio para definir Azure recursos. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Ao publicares a tua aplicação, o Bicep gerado é exibido juntamente com o ficheiro de manifesto. Quando se adiciona um recurso AzureAzure Cache for Redis, o seguinte código Bicep é gerado:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalName string

resource redis 'Microsoft.Cache/redis@2024-03-01' = {
  name: take('redis-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    sku: {
      name: 'Basic'
      family: 'C'
      capacity: 1
    }
    enableNonSslPort: false
    disableAccessKeyAuthentication: true
    minimumTlsVersion: '1.2'
    redisConfiguration: {
      'aad-enabled': 'true'
    }
  }
  tags: {
    'aspire-resource-name': 'redis'
  }
}

resource redis_contributor 'Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01' = {
  name: take('rediscontributor${uniqueString(resourceGroup().id)}', 24)
  properties: {
    accessPolicyName: 'Data Contributor'
    objectId: principalId
    objectIdAlias: principalName
  }
  parent: redis
}

output connectionString string = '${redis.properties.hostName},ssl=true'

O Bicep precedente é um módulo que provisiona um AzureAzure Cache for Redis com as seguintes configurações predefinidas:

  • location: A localização do recurso AzureAzure Cache for Redis. O padrão é o local do grupo de recursos.
  • principalId: A ID principal do recurso AzureAzure Cache for Redis.
  • principalName: O nome principal do recurso AzureAzure Cache for Redis.
  • sku: O SKU do recurso AzureAzure Cache for Redis. O padrão é Basic com uma capacidade de 1.
  • enableNonSslPort: A porta não-SSL do recurso AzureAzure Cache for Redis. O padrão é false.
  • disableAccessKeyAuthentication: A autenticação da chave de acesso do recurso AzureAzure Cache for Redis. O padrão é true.
  • minimumTlsVersion: A versão TLS mínima do recurso AzureAzure Cache for Redis. O padrão é 1.2.
  • redisConfiguration: A configuração Redis do recurso Azure Cache for Redis. O padrão é aad-enabled definido como true.
  • tags: As tags do recurso AzureAzure Cache for Redis. O padrão é aspire-resource-name definido como o nome do recurso Aspire, neste caso redis.
  • redis_contributor: O contribuidor do recurso AzureAzure Cache for Redis, com um nome de política de acesso de Data Contributor.
  • connectionString: A cadeia de conexão do recurso AzureAzure Cache for Redis.

Além do AzureAzure Cache for Redis, ele também provisiona uma atribuição de política de acesso para o aplicativo acessar o cache. O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado, fornecendo uma API fluente para configurar os recursos Azure — usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, consistencyPolicy, locationse muito mais. O exemplo a seguir demonstra como personalizar o recurso AzureAzure Cache for Redis:

builder.AddAzureRedis("redis")
    .WithAccessKeyAuthentication()
    .ConfigureInfrastructure(infra =>
    {
        var redis = infra.GetProvisionableResources()
                         .OfType<RedisResource>()
                         .Single();

        redis.Sku = new()
        {
            Family = RedisSkuFamily.BasicOrStandard,
            Name = RedisSkuName.Standard,
            Capacity = 1,                    
        };
        redis.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

  • Encadeia uma chamada para a API ConfigureInfrastructure:
    • O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
    • Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
    • O único RedisResource foi recuperado.
    • O Sku é definido com uma família de BasicOrStandard, um nome de Standard, e uma capacidade de 1.
    • Uma tag é adicionada ao recurso Redis com uma chave de ExampleKey e um valor de Example value.

Há muito mais opções de configuração disponíveis para personalizar o recurso AzureAzure Cache for Redis. Para obter mais informações, consulte Azure.Provisioning.Redis. Para obter mais informações, consulte Azure. Personalização de provisionamento.

Conectar-se a um AzureAzure Cache for Redis existente

Você pode ter um AzureAzure Cache for Redis existente ao qual deseja se conectar. Em vez de representar um novo recurso AzureAzure Cache for Redis, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a um AzureAzure Cache for Redisexistente, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddConnectionString("azure-redis");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cache);

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

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada nas definições do anfitrião da aplicação, normalmente na secção Segredos do Usuário, na secção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
    "ConnectionStrings": {
        "azure-redis": "<your-redis-name>.redis.cache.windows.net:6380,ssl=true,abortConnect=False"
    }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como parâmetro, neste caso "azure-redis". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Executar AzureAzure Cache for Redis recurso como um contêiner

A integração de hospedagem Azure Cache for Redis suporta a execução do servidor Redis como um contêiner local. Isso é benéfico para situações em que você deseja executar o servidor Redis localmente para fins de desenvolvimento e teste, evitando a necessidade de provisionar um recurso Azure ou conectar-se a um servidor Azure Cache for Redis existente.

Para usar a imagem de contêiner do docker.io/library/redis e executar a instância AzureAzure Cache for Redis como um contêiner localmente, encadeie uma chamada para RunAsContainer, conforme mostrado no exemplo a seguir:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .RunAsContainer();

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

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

O código anterior configura o recurso Redis para ser executado localmente em um contêiner.

Dica

O método RunAsContainer é útil para o desenvolvimento local e testes. A API expõe um delegado opcional que permite personalizar a configuração subjacente de RedisResource, como adicionar Redis Insights, Redis Commander, adicionar um volume de dados ou uma montagem de ligação de dados. Para obter mais informações, consulte a .NET AspireRedisintegração de hospedagem.

Configurar o recurso AzureAzure Cache for Redis para usar a autenticação de chave de acesso

Por padrão, o recurso AzureAzure Cache for Redis é configurado para usar a autenticação Microsoft Entra ID . Se você quiser usar a autenticação de senha (não recomendado), você pode configurar o servidor para usar a autenticação de senha chamando o método WithAccessKeyAuthentication:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .WithAccessKeyAuthentication();

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

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

O código anterior configura o recurso AzureAzure Cache for Redis para usar a autenticação de chave de acesso. Isso modifica o Bicep gerado para utilizar autenticação por chave de acesso em vez de autenticação do Microsoft Entra ID. Em outras palavras, a cadeia de conexão conterá uma senha e será adicionada a um segredo Azure Key Vault.

Client integração

Para começar a usar a integração do cliente .NET Aspire do Redis Stack Exchange, instale o pacote NuGet 📦Aspire.StackExchange.Redis no projeto cliente-consumidor, isto é, no projeto da aplicação que utiliza o cliente Redis. A integração de cliente Redis registra uma instância de IConnectionMultiplexer que você pode usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis

Adicionar Redis cliente

No arquivo Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddRedisClient em qualquer IHostApplicationBuilder para registrar um IConnectionMultiplexer para utilização através do contentor 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 AzureAzure Cache for Redis no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar AzureAzure Cache for Redis recurso.

Em seguida, você pode recuperar a instância IConnectionMultiplexer 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 mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar AzureAzure Cache for Redis cliente autenticado

Por padrão, quando você chama AddAzureRedis em sua integração de hospedagem Redis, ele configura o ID do Microsoft Entra. Instale o pacote NuGet 📦 Microsoft.Azure.StackExchangeRedis para ativar a autenticação.

dotnet add package Microsoft.Azure.StackExchangeRedis

A conexão Redis pode ser consumida usando a integração do cliente 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.

Adicionar cliente Redis 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, você pode recuperar as instâncias IConnectionMultiplexer usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

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

Configuração

A integração do cliente .NET Aspire do Redis 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");

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": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Para obter 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, para configurar o DisableTracing:

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

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

Por padrão, as integrações de cliente têm as verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam pontos de extremidade de verificação de integridade. Para mais informações, consulte:

A integração do .NET Aspire Stack Exchange Redis trata dos seguintes assuntos:

  • Adiciona a verificação de integridade quando StackExchangeRedisSettings.DisableHealthChecks é false, que tenta se conectar à instância do contêiner.
  • Integra-se com o ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registadas devem ser concluídas 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 Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção 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 do .NET Aspire Stack Exchange emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

Atualmente, a integração .NET Aspire Stack Exchange Redis não oferece suporte a métricas por padrão devido a limitações com a biblioteca StackExchange.Redis.

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?