Compartilhar via

.NET Aspire Azure Cache for Redis®* distributed caching integration

  • Artigo

Includes: Hosting integration and Client integration

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 de Azure Cache for Redis existentes ou crie novas instâncias de .NET com a imagem de contêiner docker.io/library/redis.

Integração de hospedagem

O modelo de integração de hospedagem .NET AspireAzure Cache for Redis modela um recurso AzureRedis como o tipo AzureRedisCacheResource. To access this type and APIs for expressing them as resources in your app host project, add the 📦Aspire.Hosting.Azure.Redis NuGet package:

dotnet add package Aspire.Hosting.Azure.Redis

For more information, see dotnet add package or Manage package dependencies in .NET applications.

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 ser implantado como um Azure Cache for Redis.

Important

By default, AddAzureRedis configures Microsoft Entra ID authentication. Isso requer alterações em aplicativos que precisam se conectar a esses recursos, por exemplo, integrações de cliente.

Tip

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.

Generated provisioning Bicep

If you're new to Bicep, it's a domain-specific language for defining Azure resources. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, pois as APIs de provisionamento geram Bicep para você. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an AzureAzure Cache for Redis resource, the following Bicep is generated:

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

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'
  }
}

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

output name string = redis.name

O Bicep mencionado anteriormente é um módulo que provisiona um AzureAzure Cache for Redis recurso. Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

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

param redis_outputs_name string

param principalId string

param principalName string

resource redis 'Microsoft.Cache/redis@2024-03-01' existing = {
  name: redis_outputs_name
}

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

In addition to the AzureAzure Cache for Redis, it also provisions an access policy assignment to the application access to the cache. O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. 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:

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. For more information, see Azure.Provisioning customization.

Conectar-se a um AzureAzure Cache for Redis existente

Você pode ter uma AzureAzure Cache for Redis existente à qual deseja se conectar. Em vez de representar um novo recurso de 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...

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 de GetConnectionString é abreviada para 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.

Tip

O método RunAsContainer é útil para desenvolvimento e teste locais. The API exposes an optional delegate that enables you to customize the underlying RedisResource configuration, such adding Redis Insights, Redis Commander, adding a data volume or data bind mount. 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. This alters the generated Bicep to use access key authentication instead of Microsoft Entra ID authentication. Em outras palavras, a cadeia de conexão conterá uma senha e será adicionada a um segredo Azure Key Vault.

integração Client

To get started with the .NET AspireRedis distributed caching integration, install the 📦Aspire.StackExchange.Redis.DistributedCaching NuGet package in the client-consuming project, i.e., the project for the application that uses the Redis distributed caching client. A integração do cliente Redis registra uma instância de IDistributedCache que você pode usar para interagir com Redis.

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

Adicionar Redis cliente de cache distribuído

In the Program.cs file of your client-consuming project, call the AddRedisDistributedCache extension to register the required services for distributed caching and add a IDistributedCache for use via the dependency injection container.

builder.AddRedisDistributedCache(connectionName: "cache");

Tip

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso AzureAzure Cache for Redis no projeto de host do aplicativo. For more information, see Add AzureAzure Cache for Redis resource.

You can then retrieve the IDistributedCache instance using dependency injection. Por exemplo, para recuperar o cache de um serviço:

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

For more information on dependency injection, see .NET dependency injection.

Adicionar AzureAzure Cache for Redis cliente distribuído autenticado

By default, when you call AddAzureRedis in your app host project, the Redis hosting integration configures 📦 Microsoft.Azure.StackExchangeRedis NuGet package to enable authentication:

dotnet add package Microsoft.Azure.StackExchangeRedis

The Redis connection can be consumed using the client integration and 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.AddRedisDistributedCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

For more information, see the Microsoft.Azure.StackExchangeRedis repo.

Add keyed Redis client

Pode haver situações em que você deseja registrar várias instâncias de IDistributedCache com nomes de conexão diferentes. To register keyed Redis clients, call the AddKeyedRedisDistributedCache method:

builder.AddKeyedRedisDistributedCache(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");

Then you can retrieve the IDistributedCache instances using dependency injection. Por exemplo, para recuperar a conexão de um serviço de exemplo:

public class ExampleService(
    [FromKeyedServices("chat")] IDistributedCache chatCache,
    [FromKeyedServices("product")] IDistributedCache productCache)
{
    // Use caches...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuração

A integração de cache distribuído .NET AspireRedis fornece várias opções para configurar a conexão Redis com base nos requisitos e convenções do seu projeto.

Use a connection string

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 builder.AddRedisDistributedCache:

builder.AddRedisDistributedCache("cache");

Em seguida, a cadeia de conexão será recuperada da seção de configuração do 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 de cache distribuída do .NET Aspire Stack Exchange Redis dá suporte a Microsoft.Extensions.Configuration. It loads the StackExchangeRedisSettings from configuration by using the Aspire:StackExchange:Redis key. Exemplo appsettings.json que configura algumas das opções:

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

For the complete Redis distributed caching client integration JSON schema, see Aspire.StackExchange.Redis.DistributedCaching/ConfigurationSchema.json.

Use inline delegates

You can also pass the Action<StackExchangeRedisSettings> delegate to set up some or all the options inline, for example to configure DisableTracing:

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

Você também pode configurar o ConfigurationOptions usando o parâmetro delegado Action<ConfigurationOptions> configureOptions do método AddRedisDistributedCache. Por exemplo, para definir o tempo limite da conexão:

builder.AddRedisDistributedCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

Client integration health checks

By default, .NET.NET Aspireclient integrations have health checks enabled for all services. Similarly, many .NET.NET Aspirehosting integrations also enable health check endpoints. Para obter mais informações, consulte:

The .NET AspireRedis distributed caching integration handles the following:

  • Adds the health check when StackExchangeRedisSettings.DisableHealthChecks is false, which attempts to connect to the container instance.
  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo seja considerado preparado para receber tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente registros, 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.

Logging

A integração de cache distribuída .NET AspireRedis usa as seguintes categorias de log:

  • Aspire.StackExchange.Redis
  • Microsoft.Extensions.Caching.StackExchangeRedis

Tracing

The .NET AspireRedis distributed caching integration will emit the following Tracing activities using OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

The .NET AspireRedis Distributed caching integration currently doesn't support metrics by default due to limitations with the StackExchange.Redis library.

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. Retornar àsuperior?