Add Azure Cache for Redis standalone content (#2545)

* Minor clean up of existing Redis overview page * Fix typo in existing content * Initial bits... * A few more updates * Added hosting bits * More include magic and movement * Remove dup code segments. * Update client bits * Fix validation errors * Lots of fixes and corrections * Correct a few includes after spot checking * Add a few Azure logos to enlighten our readers * More clean up * Revert image changes * Fix queue image src * Fix link * Apply suggestions from code review Co-authored-by: Sébastien Ros <[email protected]> * Apply suggestions from code review Co-authored-by: Eric Erhardt <[email protected]> --------- Co-authored-by: Sébastien Ros <[email protected]> Co-authored-by: Eric Erhardt <[email protected]>
dotnet · Feb 10, 2025 · bc4f9b1 · bc4f9b1
1 parent 49287ff
commit bc4f9b1
Show file tree

Hide file tree

Showing 46 changed files with 815 additions and 474 deletions.
diff --git a/docs/azureai/azureai-search-document-integration.md b/docs/azureai/azureai-search-document-integration.md
@@ -186,7 +186,7 @@ builder.AddAzureSearch(
         static options => options.Diagnostics.ApplicationId = "CLIENT_ID"));
 ```
 
-[!INCLUDE [integration-health-checks](../includes/integration-health-checks.md)]
+[!INCLUDE [client-integration-health-checks](../includes/client-integration-health-checks.md)]
 
 The .NET Aspire Azure AI Search Documents integration implements a single health check, that calls the <xref:Azure.Search.Documents.Indexes.SearchIndexClient.GetServiceStatisticsAsync%2A> method on the `SearchIndexClient` to verify that the service is available.
 

diff --git a/docs/caching/azure-cache-for-redis-distributed-caching-integration.md b/docs/caching/azure-cache-for-redis-distributed-caching-integration.md
@@ -0,0 +1,126 @@
+---
+title: Azure Cache for Redis distributed caching integration
+description: Learn how to integrate Azure Cache for Redis as a distributed caching solution with the .NET Aspire stack.
+ms.date: 02/05/2025
+---
+
+# .NET Aspire Azure Cache for Redis&reg;<sup>**[*](#registered)**</sup> distributed caching integration
+
+<a name="heading"></a>
+
+[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]
+
+[!INCLUDE [azure-redis-intro](includes/azure-redis-intro.md)]
+
+The .NET Aspire Azure Cache for Redis integration enables you to connect to existing Azure Cache for Redis instances, or create new instances from .NET with the [`docker.io/library/redis` container image](https://hub.docker.com/_/redis/).
+
+## Hosting integration
+
+[!INCLUDE [azure-redis-app-host](includes/azure-redis-app-host.md)]
+
+## Client integration
+
+[!INCLUDE [redis-distributed-client-nuget](includes/redis-distributed-client-nuget.md)]
+
+### Add Redis distributed cache client
+
+In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireRedisDistributedCacheExtensions.AddRedisDistributedCache%2A> extension to register the required services for distributed caching and add a <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> for use via the dependency injection container.
+
+```csharp
+builder.AddRedisDistributedCache(connectionName: "cache");
+```
+
+> [!TIP]
+> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource).
+
+You can then retrieve the `IDistributedCache` instance using dependency injection. For example, to retrieve the cache from a service:
+
+```csharp
+public class ExampleService(IDistributedCache cache)
+{
+    // Use cache...
+}
+```
+
+For more information on dependency injection, see [.NET dependency injection](/dotnet/core/extensions/dependency-injection).
+
+[!INCLUDE [azure-redis-distributed-client](includes/azure-redis-distributed-client.md)]
+
+### Add keyed Redis client
+
+There might be situations where you want to register multiple `IDistributedCache` instances with different connection names. To register keyed Redis clients, call the <xref:Microsoft.Extensions.Hosting.AspireRedisDistributedCacheExtensions.AddKeyedRedisDistributedCache*> method:
+
+```csharp
+builder.AddKeyedRedisDistributedCache(name: "chat");
+builder.AddKeyedRedisDistributedCache(name: "product");
+```
+
+Then you can retrieve the `IDistributedCache` instances using dependency injection. For example, to retrieve the connection from an example service:
+
+```csharp
+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](/dotnet/core/extensions/dependency-injection#keyed-services).
+
+### Configuration
+
+The .NET Aspire Redis distributed caching integration provides multiple options to configure the Redis connection based on the requirements and conventions of your project.
+
+#### Use a connection string
+
+When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddRedisDistributedCache`:
+
+```csharp
+builder.AddRedisDistributedCache("cache");
+```
+
+And then the connection string will be retrieved from the `ConnectionStrings` configuration section:
+
+```json
+{
+  "ConnectionStrings": {
+    "cache": "localhost:6379"
+  }
+}
+```
+
+For more information on how to format this connection string, see the [Stack Exchange Redis configuration docs](https://stackexchange.github.io/StackExchange.Redis/Configuration.html#basic-configuration-strings).
+
+#### Use configuration providers
+
+[!INCLUDE [redis-distributed-client-json-settings](includes/redis-distributed-client-json-settings.md)]
+
+#### 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`:
+
+```csharp
+builder.AddRedisDistributedCache(
+    "cache",
+    settings => settings.DisableTracing = true);
+```
+
+You can also set up the [ConfigurationOptions](https://stackexchange.github.io/StackExchange.Redis/Configuration.html#configuration-options) using the `Action<ConfigurationOptions> configureOptions` delegate parameter of the `AddRedisDistributedCache` method. For example to set the connection timeout:
+
+```csharp
+builder.AddRedisDistributedCache(
+    "cache",
+    static settings => settings.ConnectTimeout = 3_000);
+```
+
+[!INCLUDE [redis-distributed-client-health-checks-and-diagnostics](includes/redis-distributed-client-health-checks-and-diagnostics.md)]
+
+## See also
+
+- [Azure Cache for Redis docs](/azure/azure-cache-for-redis/)
+- [Stack Exchange Redis docs](https://stackexchange.github.io/StackExchange.Redis/)
+- [.NET Aspire integrations](../fundamentals/integrations-overview.md)
+- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)
+
+[!INCLUDE [redis-trademark](includes/redis-trademark.md)]
diff --git a/docs/caching/azure-cache-for-redis-integration.md b/docs/caching/azure-cache-for-redis-integration.md
@@ -0,0 +1,118 @@
+---
+title: Azure Cache for Redis integration
+description: Learn how to integrate Azure Cache for Redis with the .NET Aspire stack.
+ms.date: 02/05/2025
+---
+
+# .NET Aspire Azure Cache for Redis&reg;<sup>**[*](#registered)**</sup> integration
+
+<a name="heading"></a>
+
+[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]
+
+[!INCLUDE [azure-redis-intro](includes/azure-redis-intro.md)]
+
+The .NET Aspire Azure Cache for Redis integration enables you to connect to existing Azure Cache for Redis instances, or create new instances, or run as a container locally from .NET with the [`docker.io/library/redis` container image](https://hub.docker.com/_/redis/).
+
+## Hosting integration
+
+[!INCLUDE [azure-redis-app-host](includes/azure-redis-app-host.md)]
+
+## Client integration
+
+[!INCLUDE [redis-client-nuget](includes/redis-client-nuget.md)]
+
+### 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.
+
+```csharp
+builder.AddRedisClient(connectionName: "cache");
+```
+
+> [!TIP]
+> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource).
+
+You can then retrieve the `IConnectionMultiplexer` instance using dependency injection. For example, to retrieve the connection from an example service:
+
+```csharp
+public class ExampleService(IConnectionMultiplexer connectionMux)
+{
+    // Use connection multiplexer...
+}
+```
+
+For more information on dependency injection, see [.NET dependency injection](/dotnet/core/extensions/dependency-injection).
+
+[!INCLUDE [azure-redis-client](includes/azure-redis-client.md)]
+
+### 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:
+
+```csharp
+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:
+
+```csharp
+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](/dotnet/core/extensions/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
+
+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*>:
+
+```csharp
+builder.AddRedis("cache");
+```
+
+Then the connection string will be retrieved from the `ConnectionStrings` configuration section:
+
+```json
+{
+  "ConnectionStrings": {
+    "cache": "localhost:6379"
+  }
+}
+```
+
+For more information on how to format this connection string, see the [Stack Exchange Redis configuration docs](https://stackexchange.github.io/StackExchange.Redis/Configuration.html#basic-configuration-strings).
+
+#### Use configuration providers
+
+[!INCLUDE [redis-client-json-settings](includes/redis-client-json-settings.md)]
+
+#### 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`:
+
+```csharp
+builder.AddRedisClient(
+    "cache",
+    static settings => settings.DisableTracing = true);
+```
+
+[!INCLUDE [redis-client-health-checks-and-diagnostics](includes/redis-client-health-checks-and-diagnostics.md)]
+
+## See also
+
+- [Azure Cache for Redis docs](/azure/azure-cache-for-redis/)
+- [Stack Exchange Redis docs](https://stackexchange.github.io/StackExchange.Redis/)
+- [.NET Aspire integrations](../fundamentals/integrations-overview.md)
+- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)
+
+[!INCLUDE [redis-trademark](includes/redis-trademark.md)]
diff --git a/docs/caching/azure-cache-for-redis-output-caching-integration.md b/docs/caching/azure-cache-for-redis-output-caching-integration.md
@@ -0,0 +1,114 @@
+---
+title: Azure Cache for Redis output caching integration
+description: Learn how to integrate Azure Cache for Redis as an output caching solution with the .NET Aspire stack.
+ms.date: 02/05/2025
+---
+
+# .NET Aspire Azure Cache for Redis&reg;<sup>**[*](#registered)**</sup> output caching integration
+
+<a name="heading"></a>
+
+[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]
+
+[!INCLUDE [azure-redis-intro](includes/azure-redis-intro.md)]
+
+The .NET Aspire Azure Cache for Redis integration enables you to connect to existing Azure Cache for Redis instances, or create new instances from .NET with the [`docker.io/library/redis` container image](https://hub.docker.com/_/redis/).
+
+## Hosting integration
+
+[!INCLUDE [azure-redis-app-host](includes/azure-redis-app-host.md)]
+
+## Client integration
+
+[!INCLUDE [redis-output-client-nuget](includes/redis-output-client-nuget.md)]
+
+### Add output caching
+
+In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireRedisOutputCacheExtensions.AddRedisOutputCache%2A> extension method on any <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> to register the required services for output caching.
+
+```csharp
+builder.AddRedisOutputCache(connectionName: "cache");
+```
+
+> [!TIP]
+> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource).
+
+Add the middleware to the request processing pipeline by calling <xref:Microsoft.AspNetCore.Builder.OutputCacheApplicationBuilderExtensions.UseOutputCache(Microsoft.AspNetCore.Builder.IApplicationBuilder)>:
+
+```csharp
+var app = builder.Build();
+
+app.UseOutputCache();
+```
+
+For [minimal API apps](/aspnet/core/fundamentals/minimal-apis/overview), configure an endpoint to do caching by calling <xref:Microsoft.Extensions.DependencyInjection.OutputCacheConventionBuilderExtensions.CacheOutput%2A>, or by applying the <xref:Microsoft.AspNetCore.OutputCaching.OutputCacheAttribute>, as shown in the following examples:
+
+```csharp
+app.MapGet("/cached", () => "Hello world!")
+   .CacheOutput();
+
+app.MapGet(
+    "/attribute",
+    [OutputCache] () => "Hello world!");
+```
+
+For apps with controllers, apply the `[OutputCache]` attribute to the action method. For Razor Pages apps, apply the attribute to the Razor page class.
+
+[!INCLUDE [azure-redis-output-client](includes/azure-redis-output-client.md)]
+
+### Configuration
+
+The .NET Aspire Stack Exchange Redis output caching integration provides multiple options to configure the Redis connection based on the requirements and conventions of your project.
+
+#### Use a connection string
+
+When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling <xref:Microsoft.Extensions.Hosting.AspireRedisOutputCacheExtensions.AddRedisOutputCache*>:
+
+```csharp
+builder.AddRedisOutputCache(connectionName: "cache");
+```
+
+Then the connection string will be retrieved from the `ConnectionStrings` configuration section:
+
+```json
+{
+  "ConnectionStrings": {
+    "cache": "localhost:6379"
+  }
+}
+```
+
+For more information on how to format this connection string, see the [Stack Exchange Redis configuration docs](https://stackexchange.github.io/StackExchange.Redis/Configuration.html#basic-configuration-strings).
+
+#### Use configuration providers
+
+[!INCLUDE [redis-output-client-json-settings](includes/redis-output-client-json-settings.md)]
+
+#### Use inline delegates
+
+You can also pass the `Action<StackExchangeRedisSettings> configurationSettings` delegate to set up some or all the options inline, for example to disable health checks from code:
+
+```csharp
+builder.AddRedisOutputCache(
+    "cache",
+    static settings => settings.DisableHealthChecks  = true);
+```
+
+You can also set up the [ConfigurationOptions](https://stackexchange.github.io/StackExchange.Redis/Configuration.html#configuration-options) using the `Action<ConfigurationOptions> configureOptions` delegate parameter of the <xref:Microsoft.Extensions.Hosting.AspireRedisOutputCacheExtensions.AddRedisOutputCache%2A> method. For example to set the connection timeout:
+
+```csharp
+builder.AddRedisOutputCache(
+    "cache",
+    static settings => settings.ConnectTimeout = 3_000);
+```
+
+[!INCLUDE [redis-output-client-health-checks-and-diagnostics](includes/redis-output-client-health-checks-and-diagnostics.md)]
+
+## See also
+
+- [Azure Cache for Redis docs](/azure/azure-cache-for-redis/)
+- [Stack Exchange Redis docs](https://stackexchange.github.io/StackExchange.Redis/)
+- [.NET Aspire integrations](../fundamentals/integrations-overview.md)
+- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)
+
+[!INCLUDE [redis-trademark](includes/redis-trademark.md)]
diff --git a/docs/caching/caching-integrations.md b/docs/caching/caching-integrations.md
@@ -1,7 +1,7 @@
 ---
 title: Implement caching with .NET Aspire integrations
 description: Learn how to connect to Redis and cache data using .NET Aspire integrations.
-ms.date: 11/08/2024
+ms.date: 02/05/2025
 ms.topic: tutorial
 ---
 
@@ -172,7 +172,7 @@ Configuring connection string with this method, while functional, requires dupli
             await cache.SetAsync("forecast", Encoding.UTF8.GetBytes(JsonSerializer.Serialize(forecast)), new ()
             {
                 AbsoluteExpiration = DateTime.Now.AddSeconds(10)
-            }); ;
+            });
 
             return forecast;
         }