.NET Aspire Azure Cache for Redis®^* 集成

包含： - Client 集成

Azure Cache for Redis 提供了一种基于 Redis 软件的内存数据存储。 Redis 可提高使用后端数据存储的应用程序的性能和可伸缩性。 它可以通过在服务器内存中保留经常访问的数据来处理大量应用程序请求，这些数据可以快速写入和读取。 Redis 为新式应用程序带来了关键的低延迟和高吞吐量数据存储解决方案。

Azure Cache for Redis 提供 Redis 开源（OSS Redis）和来自 Redis 公司（Redis 企业）的商业产品作为托管服务。 它提供安全专用 Redis 服务器实例以及完整的 Redis API 兼容性。 Microsoft运行服务，托管在 Azure上，可由 Azure内外的任何应用程序使用。

通过 .NET AspireAzure Cache for Redis 集成，可以连接到现有 Azure Cache for Redis 实例，或创建新实例，或者通过 .NET从本地 docker.io/library/redis 作为容器运行。

托管集成

托管集成 .NET AspireAzure Cache for Redis 将 AzureRedis 资源建模为 AzureRedisCacheResource 类型。 若要访问此类型和 API，并将其在应用主机项目中表示为资源，请添加 📦Aspire.Hosting.Azure.Redis NuGet 包。

dotnet add package Aspire.Hosting.Azure.Redis

<PackageReference Include="Aspire.Hosting.Azure.Redis"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或 管理.NET应用程序中的包依赖项。

添加 AzureAzure Cache for Redis 资源

在应用主机项目中，对 AddAzureRedis 实例调用 builder 以添加 AzureAzure Cache for Redis 资源，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

上述 AddAzureRedis 调用将 Redis 服务器资源配置为 Azure Cache for Redis。

由预配生成的 Bicep

如果你不熟悉 Bicep，则它是用于定义 Azure 资源的特定于域的语言。 使用 .NET.NET Aspire，无需手动编写 Bicep，而是预配 API 会为你生成 Bicep。 发布应用时，生成的 Bicep 文件将随清单文件一起输出。 添加 AzureAzure Cache for Redis 资源时，将生成以下 Bicep：

@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

上述的 Bicep 模块是用于预配 AzureAzure Cache for Redis 资源的。 此外，在单独的模块中为 Azure 资源创建角色分配：

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

除了 AzureAzure Cache for Redis，它还为应用程序对缓存访问预配了访问策略分配。 生成的 Bicep 作为起点，受 C# 中资源配置基础设施更改的影响。 直接对 Bicep 文件的自定义项所做的更改将被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。 此类型提供了一种流畅的 API，可以通过 Azure API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，从而实现对生成的 Bicep 的自定义。 例如，可以配置 kind、consistencyPolicy、locations等。 以下示例演示如何自定义 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");
    });

前面的代码：

• 将一次调用与 ConfigureInfrastructure API 链接
  • infra 参数是 AzureResourceInfrastructure 类型的实例。
  • 通过调用 GetProvisionableResources() 方法检索可预配资源。
  • 单个 RedisResource 已被检索。
  • Sku 被设置为一系列 BasicOrStandard、名字为 Standard 和容量为 1。
  • 将一个标记添加到具有 Redis 键和 ExampleKey值的 Example value 资源中。

还有更多配置选项可用于自定义 AzureAzure Cache for Redis 资源。 有关详细信息，请参阅 Azure.Provisioning.Redis。 有关详细信息，请参阅 Azure预配自定义。

连接到现有 AzureAzure Cache for Redis

你可能有一个现有的对象AzureAzure Cache for Redis需要连接。 不必创建新的 AzureAzure Cache for Redis 资源，而可以向应用主机添加连接字符串。 若要将连接添加到现有 AzureAzure Cache for Redis，请调用 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...

连接字符串是在应用主机的配置中配置的，通常在 部分下的 ConnectionStrings下。 应用主机将此连接字符串作为环境变量注入到所有依赖资源中，例如：

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

依赖资源可以通过调用 GetConnectionString 方法并传递连接名称作为参数来访问注入的连接字符串，在本例中为 "azure-redis"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的简写。

以容器身份运行 AzureAzure Cache for Redis 资源

托管集成 Azure Cache for Redis 支持将 Redis 服务器作为本地容器运行。 这适用于想要在本地运行 Redis 服务器以进行开发和测试，避免需要预配 Azure 资源或连接到现有 Azure Cache for Redis 服务器的情况。

若要使用 docker.io/library/redis 容器映像，并在本地作为容器运行 AzureAzure Cache for Redis 实例，请将调用链接到 RunAsContainer，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

前面的代码将 Redis 资源配置为在容器中本地运行。

配置 AzureAzure Cache for Redis 资源以使用访问密钥身份验证

默认情况下，资源 AzureAzure Cache for Redis 配置为使用 Microsoft Entra ID 身份验证。 如果要使用密码身份验证（不建议），可以通过调用 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...

前面的代码将 AzureAzure Cache for Redis 资源配置为使用访问密钥身份验证。 这会更改生成的 Bicep 以使用访问密钥身份验证，而不是Microsoft Entra ID 身份验证。 换句话说，连接字符串将包含密码，并将被添加到Azure Key Vault机密中。

Client 集成

若要开始进行 .NET Aspire Stack Exchange Redis 客户端集成，请在应用程序使用📦客户端的项目中安装 Redis 的 NuGet 包。 Redis客户端集成注册一个 IConnectionMultiplexer 实例，该实例可用于与 RedisIConnectionMultiplexer 实例进行交互。

dotnet add package Aspire.StackExchange.Redis

<PackageReference Include="Aspire.StackExchange.Redis"
                  Version="*" />

添加 Redis 客户端

在客户端使用项目的 Program.cs 文件中，对任何 AddRedisClient 调用 IHostApplicationBuilder 扩展方法，以注册 IConnectionMultiplexer，以便通过依赖项注入容器使用。 该方法采用连接名称参数。

builder.AddRedisClient(connectionName: "cache");

然后，可以使用依赖项注入检索 IConnectionMultiplexer 实例。 例如，若要从示例服务检索连接，

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加经过身份验证的 AzureAzure Cache for Redis 客户端

默认情况下，在 AddAzureRedis 托管集成中调用 Redis 时，它将配置 Microsoft Entra ID。 📦安装 Microsoft.Azure.StackExchangeRedis NuGet 包以启用身份验证：

dotnet add package Microsoft.Azure.StackExchangeRedis

<PackageReference Include="Microsoft.Azure.StackExchangeRedis"
                  Version="*" />

可以通过客户端集成和 Redis 消费 Microsoft.Azure.StackExchangeRedis 连接。 请考虑以下配置代码：

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;
});

有关详细信息，请参阅 Microsoft。Azure。StackExchangeRedis 存储库。

添加有密钥的 Redis 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 IConnectionMultiplexer 实例。 若要注册密钥 Redis 客户端，请调用 AddKeyedRedisClient 方法：

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

然后，可以使用依赖项注入检索 IConnectionMultiplexer 实例。 例如，若要从示例服务检索连接，

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

有关密钥服务的详细信息，请参阅 .NET 依赖关系注入：密钥服务。

配置

.NET Aspire Stack Exchange Redis 客户端集成提供了多个选项，用于根据项目的要求和约定配置 Redis 连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddRedis时提供连接字符串的名称：

builder.AddRedis("cache");

然后，将从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

有关如何设置此连接字符串格式的详细信息，请参阅 Stack Exchange Redis 配置文档。

使用配置提供程序

.NET Aspire Stack Exchange Redis 集成支持 Microsoft.Extensions.Configuration。 它使用 StackExchangeRedisSettings 键从配置文件中加载 Aspire:StackExchange:Redis。 配置某些选项的示例 appsettings.json：

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

有关完整的 Redis 客户端集成 JSON 架构，请参阅 Aspire。StackExchange。Redis/ConfigurationSchema.json.

使用内联委托

您还可以传递 Action<StackExchangeRedisSettings> 委托来设置部分或全部的内联选项，例如用于配置 DisableTracing：

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

Client 集成健康检查

默认情况下， .NET.NET Aspire客户端集成 为所有服务启用了 运行状况检查 。 同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。 有关详细信息，请参阅：

• 在 C# .NET 进行应用健康检查
• 健康检查 ASP.NET Core

.NET Aspire Stack Exchange Redis 集成处理以下内容：

• 添加运行状况检查，当StackExchangeRedisSettings.DisableHealthChecks为false时，该检查会尝试连接到容器实例。
• 与 /health HTTP 终结点集成，该终结点指定所有已注册的健康检查都必须通过，以便让应用被认为已准备好接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性支柱。 有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Stack Exchange Redis 集成使用以下日志类别：

• Aspire.StackExchange.Redis

追踪

.NET Aspire Stack Exchange Redis 集成将使用 OpenTelemetry产生以下跟踪活动：

• OpenTelemetry.Instrumentation.StackExchangeRedis

指标

由于 .NET Aspire 库的限制，Redis Stack Exchange StackExchange.Redis 集成目前默认不支持指标。

另请参阅

• Azure Azure Cache for Redis 文档
• Stack Exchange Redis 文档
• .NET .NET Aspire 集成
• .NET Aspire GitHub 回购

*： Redis 是 Redis 有限公司的注册商标。其中的任何权利都保留给 Redis 有限公司。Microsoft 的任何使用仅用于参考目的，并不表示 Redis 与 Microsoft 之间有任何赞助、认可或附属关系。返回顶部？