Skip to content

Latest commit

 

History

History
234 lines (146 loc) · 9.39 KB

stackexchange-redis-integration.md

File metadata and controls

234 lines (146 loc) · 9.39 KB
Raw
title description ms.date zone_pivot_groups
.NET Aspire Redis integration
Learn how to use the .NET Aspire Redis integration, which includes both hosting and client integrations.
11/05/2024
resp-host

.NET Aspire Redis®* integration

[!INCLUDE includes-hosting-and-client]

:::zone pivot="redis"

Redis is the world's fastest data platform for caching, vector search, and NoSQL databases. The .NET Aspire Redis integration enables you to connect to existing Redis instances, or create new instances from .NET with the docker.io/library/redis container image.

:::zone-end :::zone pivot="garnet"

Garnet is a a high-performance cache-store from Microsoft Research and complies with the Redis serialization protocol (RESP). The .NET Aspire Redis integration enables you to connect to existing Garnet instances, or create new instances from .NET with the ghcr.io/microsoft/garnet container image.

:::zone-end :::zone pivot="valkey"

Valkey is a Redis fork and complies with the Redis serialization protocol (RESP). It's a high-performance key/value datastore that supports a variety of workloads such as caching, message queues, and can act as a primary database. The .NET Aspire Redis integration enables you to connect to existing Valkey instances, or create new instances from .NET with the docker.io/valkey/valkey container image.

:::zone-end

Hosting integration

:::zone pivot="redis"

[!INCLUDE redis-app-host]

:::zone-end :::zone pivot="garnet"

[!INCLUDE garnet-app-host]

:::zone-end :::zone pivot="valkey"

[!INCLUDE valkey-app-host]

:::zone-end

Hosting integration health checks

[!INCLUDE redis-hosting-health-checks]

Client integration

To get started with the .NET Aspire Stack Exchange Redis client integration, install the 📦 Aspire.StackExchange.Redis NuGet package in the client-consuming project, that is, the project for the application that uses the Redis client. The Redis client integration registers an an IConnectionMultiplexer instance that you can use to interact with Redis.

.NET CLI

dotnet add package Aspire.StackExchange.Redis

PackageReference

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

Add Redis client

In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the xref:Microsoft.Extensions.Hosting.AspireRedisExtensions.AddRedisClient* extension method on any xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder to register an IConnectionMultiplexer for use via the dependency injection container. The method takes a connection name parameter.

builder.AddRedisClient(connectionName: "cache");

:::zone pivot="redis"

Tip

The connectionName parameter must match the name used when adding the Redis resource in the app host project. For more information, see Add Redis resource.

:::zone-end :::zone pivot="garnet"

Tip

The connectionName parameter must match the name used when adding the Garnet resource in the app host project. For more information, see Add Garnet resource.

:::zone-end :::zone pivot="valkey"

Tip

The connectionName parameter must match the name used when adding the Valkey resource in the app host project. For more information, see Add Valkey resource.

:::zone-end

You can then retrieve the IConnection instance using dependency injection. For example, to retrieve the connection from an example service:

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

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

Add keyed Redis client

There might be situations where you want to register multiple IConnectionMultiplexer instances with different connection names. To register keyed Redis clients, call the xref:Microsoft.Extensions.Hosting.AspireRedisExtensions.AddKeyedRedisClient* method:

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

Then you can retrieve the IConnectionMultiplexer instances using dependency injection. For example, to retrieve the connection from an example service:

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

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

Configuration

The .NET Aspire Stack Exchange Redis client integration provides multiple options to configure the Redis connection based on the requirements and conventions of your project.

Use a connection string

:::zone pivot="redis"

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling xref:Aspire.Hosting.RedisBuilderExtensions.AddRedis*:

builder.AddRedis("cache");

:::zone-end :::zone pivot="garnet"

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling xref:Aspire.Hosting.GarnetBuilderExtensions.AddGarnet*:

builder.AddGarnet("cache");

:::zone-end :::zone pivot="valkey"

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling xref:Aspire.Hosting.ValkeyBuilderExtensions.AddValkey*:

builder.AddValkey("cache");

:::zone-end

Then the connection string will be retrieved from the ConnectionStrings configuration section:

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

For more information on how to format this connection string, see the Stack Exchange Redis configuration docs.

Use configuration providers

[!INCLUDE redis-client-json-settings]

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.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

Client integration health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.

The .NET Aspire Stack Exchange Redis integration handles the following:

  • Adds the health check when xref:Aspire.StackExchange.Redis.StackExchangeRedisSettings.DisableHealthChecks?displayProperty=nameWithType is false, which attempts to connect to the container instance.
  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Observability and telemetry

.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations might only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Stack Exchange Redis integration uses the following log categories:

  • Aspire.StackExchange.Redis

Tracing

The .NET Aspire Stack Exchange Redis integration will emit the following tracing activities using OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Metrics

The .NET Aspire Stack Exchange Redis integration currently doesn't support metrics by default due to limitations with the StackExchange.Redis library.

:::zone pivot="redis"

[!INCLUDE azure-redis-app-host]

[!INCLUDE azure-redis-client]

:::zone-end

See also

[!INCLUDE redis-trademark]