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

2025-07-18

包含： 托管集成 —&— 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 包。

.NETCLI（命令行界面）
包引用

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。

重要

默认情况下， AddAzureRedis 配置 Microsoft Entra ID 身份验证。这需要更改需要连接到这些资源的应用程序，例如客户端集成。

提示

调用 AddAzureRedis时，它会隐式调用 AddAzureProvisioning，这增加了在应用启动期间动态生成 Azure 资源的支持。应用必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置。

预配生成的 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-11-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-11-01' existing = {
  name: redis_outputs_name
}

resource redis_contributor 'Microsoft.Cache/redis/accessPolicyAssignments@2024-11-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 类型的子类。这类型通过提供用于配置 Azure 资源的流畅 API 来允许自定义生成的 Bicep - ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。例如，可以配置 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.Provisioning 自定义。

连接到现有的 AzureAzure Cache for Redis

你可能有一个要连接的现有 AzureAzure Cache for Redis 资源。你可以链接调用以标注你的 AzureRedisCacheResource 现有资源：

var builder = DistributedApplication.CreateBuilder(args);

var existingRedisName = builder.AddParameter("existingRedisName");
var existingRedisResourceGroup = builder.AddParameter("existingRedisResourceGroup");

var cache = builder.AddAzureRedis("azcache")
                   .AsExisting(existingRedisName, existingRedisResourceGroup);

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

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

重要

当您调用 RunAsExisting、PublishAsExisting 或 AsExisting 方法来处理您 Azure 订阅中已存在的资源时，必须将某些配置值添加到应用程序主机，以确保 .NET Aspire 能够找到这些资源。必要的配置值包括 SubscriptionId、 AllowResourceGroupCreation、 ResourceGroup 和 Location。如果未设置它们，仪表板中 .NET.NET Aspire 会显示“缺少配置”错误。有关如何设置它们的详细信息，请参阅 “配置”。

有关将 AzureAzure Cache for Redis 资源视为现有资源的详细信息，请参阅使用现有 Azure 资源。

注意

或者，可以选择向应用主机添加连接字符串，而不是表示 AzureAzure Cache for Redis 资源。此方法属于弱类型，不适用于角色分配或基础结构自定义。有关详细信息，请参阅添加包含连接字符串的现有 Azure 资源。

以容器身份运行 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 资源配置为在容器中本地运行。

提示

RunAsContainer 方法可用于本地开发和测试。 API 公开了一个可选委托，使你可以自定义底层 RedisResource 配置，比如添加 Redis 见解、Redis 指挥器、增加数据卷和数据绑定装载。有关详细信息，请参阅 .NET AspireRedis 托管集成。

配置 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 客户端集成，请在使用客户端的项目中安装 📦Aspire.StackExchange.Redis NuGet 包，此项目是使用 Redis 客户端的应用程序项目。 Redis客户端集成注册一个 IConnectionMultiplexer 实例，该实例可用于与 RedisIConnectionMultiplexer 实例进行交互。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.StackExchange.Redis

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

添加 Redis 客户端

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

builder.AddRedisClient(connectionName: "cache");

提示

connectionName 参数必须与在应用主机项目中添加 AzureAzure Cache for Redis 资源时使用的名称匹配。有关详细信息，请参阅 “添加 AzureAzure Cache for Redis 资源”。

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

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

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

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

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

.NETCLI（命令行界面）
包引用

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。

使用命名配置

.NET Aspire Stack Exchange Redis 集成支持命名配置，这样就可以使用不同的设置来配置同一资源类型的多个实例。命名配置使用连接名称作为主配置部分下的密钥。

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "cache1": {
          "ConfigurationOptions": {
            "ConnectTimeout": 3000,
            "ConnectRetry": 2
          },
          "DisableHealthChecks": true
        },
        "cache2": {
          "ConfigurationOptions": {
            "ConnectTimeout": 5000,
            "ConnectRetry": 3
          },
          "DisableTracing": true
        }
      }
    }
  }
}

在此示例中，当调用cache1时，可以使用cache2和AddRedisClient作为连接名称。

builder.AddRedisClient("cache1");
builder.AddRedisClient("cache2");

命名配置优先于顶级配置。如果同时提供这两种设置，则命名配置中的设置将替代顶级设置。

使用内联委托

你还可以传递 Action<StackExchangeRedisSettings> 委托，从而以内联方式设置部分或全部选项，例如用于配置 DisableTracing：

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

Client 集成运行状况检查

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

.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 集成目前默认不支持指标。

另请参阅

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