Azure Cache for Redis Hosting integration

The Aspire Azure Cache for Redis hosting integration models the Redis cache as the AzureRedisResource type. To access this type and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.Redis NuGet package:

dotnet add package Aspire.Hosting.Azure.Redis

Add an Azure Cache for Redis resource

To add an Azure Cache for Redis resource to your AppHost project, call the AddAzureManagedRedis method providing a name:

var builder = DistributedApplication.CreateBuilder(args);
  
var redis = builder.AddAzureManagedRedis("redis");
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(redis);
  
// After adding all resources, run the app...

The preceding code adds an Azure Redis resource named redis to the AppHost project. The WithReference method passes the connection information to the ExampleProject project.

Connect to an existing Azure Cache for Redis instance

You might have an existing Azure Cache for Redis service that you want to connect to. You can chain a call to annotate that your AzureRedisCacheResource is an existing resource:

var builder = DistributedApplication.CreateBuilder(args);
  
var existingRedisName = builder.AddParameter("existingRedisName");
var existingRedisResourceGroup = builder.AddParameter("existingRedisResourceGroup");
  
var redis = builder.AddAzureManagedRedis("redis")
    .AsExisting(existingRedisName, existingRedisResourceGroup);
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(redis);
  
// After adding all resources, run the app...

For more information on treating Azure Redis resources as existing resources, see Use existing Azure resources.

Run Azure Cache for Redis resource as a container

The Azure Cache for Redis hosting integration supports running the Redis server as a local container. This is beneficial for situations where you want to run the Redis server locally for development and testing purposes, avoiding the need to provision an Azure resource or connect to an existing Azure Cache for Redis server.

To make use of the docker.io/library/redis container image, and run the Azure Cache for Redis instance as a container locally, chain a call to RunAsContainer, as shown in the following example:

var builder = DistributedApplication.CreateBuilder(args);
  
var cache = builder.AddAzureManagedRedis("azcache")
    .RunAsContainer();
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(cache);
  
// After adding all resources, run the app...

The preceding code configures the Redis resource to run locally in a container.

Configure the Azure Cache for Redis resource to use access key authentication

By default, the Azure Cache for Redis resource is configured to use Microsoft Entra ID authentication. If you want to use password authentication (not recommended), you can configure the server to use password authentication by calling the WithAccessKeyAuthentication method:

var builder = DistributedApplication.CreateBuilder(args);
  
var cache = builder.AddAzureManagedRedis("azcache")
    .WithAccessKeyAuthentication();
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(cache);
  
// After adding all resources, run the app...

The preceding code configures the Azure Cache for Redis resource to use access key authentication. This alters the generated Bicep to use access key authentication instead of Microsoft Entra ID authentication. In other words, the connection string will contain a password, and will be added to an Azure Key Vault secret.

Provisioning-generated Bicep

If you're new to Bicep, it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure 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-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

The preceding Bicep is a module that provisions an Azure Cache for Redis resource. Additionally, role assignments are created for the Azure resource in a separate module:

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

In addition to the Azure Cache for Redis, it also provisions an access policy assignment to the application access to the cache. The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in 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.

Customize provisioning infrastructure

All Aspire Azure resources are subclasses of the AzureProvisioningResource type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the ConfigureInfrastructure API:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddAzureManagedRedis("redis")
    .WithAccessKeyAuthentication()
    .ConfigureInfrastructure(infra =>
    {
        var cluster = infra.GetProvisionableResources()
                           .OfType<RedisEnterpriseCluster>()
                           .Single();
  
        cluster.Sku = new RedisEnterpriseSku
        {
            Name = RedisEnterpriseSkuName.BalancedB0,
        };
        cluster.Tags.Add("ExampleKey", "Example value");
    });

The preceding code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources method.
  • The single RedisEnterpriseCluster is retrieved.
  • The Sku is set with a name of BalancedB0.
  • A tag is added to the Redis resource with a key of ExampleKey and a value of Example value.

There are many more configuration options available to customize the Redis resource. For more information, see Azure.Provisioning customization.

Connection properties

When you reference Azure Redis resources using WithReference, the following connection properties are made available to the consuming project:

Azure Redis Enterprise