Compartilhar via

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

  • Artigo

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

Azure Cache for Redis fornece um armazenamento de dados na memória com base no software Redis. Redis melhora muito o desempenho e a escalabilidade de um aplicativo que usa armazenamentos de dados de back-end. Ele é capaz de processar grandes volumes de solicitações de aplicativo 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 o Redis software livre (OSS Redis) e um produto comercial da Redis Inc. (Redis Enterprise) como um serviço gerenciado. Ele fornece instâncias de servidor Redis seguras e dedicadas e compatibilidade de API de Redis completa. A Microsoft opera o serviço, hospedado em Azuree utilizável por qualquer aplicativo dentro ou fora de Azure.

A integração .NET AspireAzure Cache for Redis permite que você se conecte a instâncias 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

Os modelos de integração de hospedagem .NET AspireAzure Cache for Redis modelam um recurso AzureRedis como o tipo AzureRedisCacheResource. Para acessar esse tipo e API para expressá-los como recurso em seu projeto de aplicativo host , 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 Gerenciar dependências de pacotes em .NET aplicativos.

Adicionar AzureAzure Cache for Redis recurso

No projeto de host do aplicativo, chame AddAzureRedis na instância builder para adicionar um recurso 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 de servidor Redis para que ele seja implantado 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— o que adiciona suporte para gerar recursos 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.

Bicep de provisionamento gerado

Se você não estiver familiarizado com Bicep, é uma linguagem de domínio específico para definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, pois as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é produzido junto com o arquivo de manifesto. Quando você adiciona um recurso AzureAzure Cache for Redis, o seguinte 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 anterior é um módulo que configura um AzureAzure Cache for Redis com os seguintes padrões:

  • 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 de 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 mínima do TLS 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 etiquetas do recurso AzureAzure Cache for Redis. O padrão é aspire-resource-name definido como o nome do recurso Aspire, nesse caso redis.
  • redis_contributor: o colaborador do recurso AzureAzure Cache for Redis, com o nome da política de acesso Data Contributor.
  • connectionString: A string 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 para o acesso do aplicativo ao cache. O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

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 ao oferecer uma API fluente para configurar os recursos de 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 de 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 à API de 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 é recuperado.
    • O Sku é configurado com uma família de BasicOrStandard, um nome de Standarde 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 de AzureAzure Cache for Redis, você pode adicionar uma string de conexão no 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...

Nota

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. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seçã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 o parâmetro, nesse 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 Azure Cache for Redis integração de hospedagem dá suporte à 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 se conectar a um servidor Azure Cache for Redis existente.

Para usar a imagem de contêiner docker.io/library/redis e executar a instância AzureAzure Cache for Redis como um contêiner localmente, encadeia 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 a ser executado localmente em um contêiner.

Dica

O método RunAsContainer é útil para desenvolvimento e teste locais. 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 integração de hospedagem .NET AspireRedis.

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 do Microsoft Entra ID . Se você quiser usar a autenticação de senha (não recomendado), poderá 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 altera o Bicep gerado para usar a autenticação de chave de acesso no lugar da 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.

integração Client

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

dotnet add package Aspire.StackExchange.Redis

Adicionar Redis cliente

No arquivo Program.cs do projeto que consome o cliente, utilize o método de extensão AddRedisClient em qualquer IHostApplicationBuilder para registrar um IConnectionMultiplexer para uso através do contêiner de injeção de dependê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 AzureAzure Cache for Redis no projeto de host do aplicativo. Para obter mais informações, consulte AdicionarAzure Cache for RedisAzurerecurso.

Em seguida, você pode recuperar a instância de 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 obter 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 Microsoft Entra ID. Instale o 📦 Microsoft.Azure.StackExchangeRedis NuGet pacote para habilitar 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. Repositório StackExchangeRedis.

Adicionar cliente categorizado Redis

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

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

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

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

Para 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 Stack Exchange Redis fornece várias opções para configurar a conexão Redis com base nos requisitos e convenções do seu projeto.

Usar uma 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");

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. Ele carrega a StackExchangeRedisSettings da configuração usando a chave Aspire:StackExchange:Redis. Exemplo appsettings.json que configura algumas das opções:

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

Para obter o esquema JSON de integração completa do cliente Redis, consulte Aspire. StackExchange.Redis/ConfigurationSchema.json.

Usar delegados embutidos

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

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

Client verificação de saúde de integração

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

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

  • Adiciona a verificação de integridade quando StackExchangeRedisSettings.DisableHealthChecks é false, que tenta se conectar à instância do contêiner.
  • Integra-se ao ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registradas devem ser aprovadas para que o aplicativo seja considerado pronto para receber tráfego.

Observabilidade e telemetria

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

Registro

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

  • Aspire.StackExchange.Redis

Rastreamento

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

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

Consulte também

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