Content for .NET Aspire - Release 8.1

.gitignore

@@ -1,3 +1,6 @@
+# Python virtual environments
+.venv
+
 docs/_build/
 .idea/
 *.swp

docfx.json

@@ -149,6 +149,7 @@
           "Docker",
           "Dockerfile",
           "EF Core",
+          "Elasticsearch",
           "Entity Framework Core",
           "Git",
           "GitHub",

docs/app-host/withdockerfile.md

@@ -0,0 +1,115 @@
+---
+title: Add Dockerfiles to your .NET app model
+description: Learn how to add Dockerfiles to your .NET app model.
+ms.date: 07/22/2024
+---
+
+# Add Dockerfiles to your .NET app model
+
+With .NET Aspire it's possible to specify a _Dockerfile_ to build when the [app host](../fundamentals/app-host-overview.md) is started using either the <xref:Aspire.Hosting.ResourceBuilderExtensions.AddDockerfile%2A> or <xref:Aspire.Hosting.ResourceBuilderExtensions.WithDockerfile%2A> extension methods.
+
+## Add a Dockerfile to the app model
+
+In the following example the <xref:Aspire.Hosting.ResourceBuilderExtensions.AddDockerfile%2A> extension method is used to specify a container by referencing the context path for the container build.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var container = builder.AddDockerfile(
+    "mycontainer", "relative/context/path");
+```
+
+Unless the context path argument is a rooted path the context path is interpreted as being relative to the app host projects directory (where the AppHost `*.csproj` folder is located).
+
+By default the name of the _Dockerfile_ which is used is `Dockerfile` and is expected to be within the context path directory. It's possible to explicitly specify the _Dockerfile_ name either as an absolute path or a relative path to the context path.
+
+This is useful if you wish to modify the specific _Dockerfile_ being used when running locally or when the app host is deploying.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var container = builder.ExecutionContext.IsRunMode
+    ? builder.AddDockerfile(
+          "mycontainer", "relative/context/path", "Dockerfile.debug")
+    : builder.AddDockerfile(
+          "mycontainer", "relative/context/path", "Dockerfile.release");
+```
+
+## Customize existing container resources
+
+When using <xref:Aspire.Hosting.ResourceBuilderExtensions.AddDockerfile%2A> the return value is an `IResourceBuilder<ContainerResource>`. .NET Aspire includes many custom resource types that are derived from <xref:Aspire.Hosting.ApplicationModel.ContainerResource>.
+
+Using the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithDockerfile%2A> extension method it's possible to continue using these strongly typed resource types and customize the underlying container that is used.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var pgsql = builder.AddPostgres("pgsql")
+                   .WithDockerfile("path/to/context")
+                   .WithPgAdmin();
+```
+
+## Pass build arguments
+
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithBuildArg%2A> method can be used to pass arguments into the container image build.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var container = builder.AddDockerfile("mygoapp", "relative/context/path")
+                       .WithBuildArg("GO_VERSION", "1.22");
+```
+
+The value parameter on the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithBuildArg%2A> method can be a literal value (`boolean`, `string`, `int`) or it can be a resource builder for a [parameter resource](../fundamentals/external-parameters.md). The following code replaces the `GO_VERSION` with a parameter value that can be specified at deployment time.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var goVersion = builder.AddParameter("goversion");
+
+var container = builder.AddDockerfile("mygoapp", "relative/context/path")
+                       .WithBuildArg("GO_VERSION", goVersion);
+```
+
+Build arguments correspond to the [`ARG` command](https://docs.docker.com/build/guide/build-args/) in _Dockerfiles_. Expanding the preceding example, this is a multi-stage _Dockerfile_ which specifies specific container image version to use as a parameter.
+
+```dockerfile
+# Stage 1: Build the Go program
+ARG GO_VERSION=1.22
+FROM golang:${GO_VERSION} AS builder
+WORKDIR /build
+COPY . .
+RUN go build mygoapp.go
+
+# Stage 2: Run the Go program
+FROM mcr.microsoft.com/cbl-mariner/base/core:2.0
+WORKDIR /app
+COPY --from=builder /build/mygoapp .
+CMD ["./mygoapp"]
+```
+
+> [!NOTE]
+> Instead of hardcoding values into the container image, it's recommended to use environment variables for values that frequently change. This avoids the need to rebuild the container image whenever a change is required.
+
+## Pass build secrets
+
+In addition to build arguments it's possible to specify build secrets using <xref:Aspire.Hosting.ResourceBuilderExtensions.WithBuildSecret%2A> which are made selectively available to individual commands in the _Dockerfile_ using the `--mount=type=secret` syntax on `RUN` commands.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var accessToken = builder.AddParameter("accesstoken", secret: true);
+
+var container = builder.AddDockerfile("myapp", "relative/context/path")
+                       .WithBuildSecret("ACCESS_TOKEN", accessToken);
+```
+
+For example, consider the `RUN` command in a _Dockerfile_ which exposes the specified secret to the specific command:
+
+```dockerfile
+# The helloworld command can read the secret from /run/secrets/ACCESS_TOKEN
+RUN --mount=type=secret,id=ACCESS_TOKEN helloworld
+```
+
+> [!CAUTION]
+> Caution should be exercised when passing secrets in build environments. This is often done when using a token to retrieve dependencies from private repositories or feeds before a build. It is important to ensure that the injected secrets are not copied into the final or intermediate images.

docs/caching/includes/garnet-app-host.md

@@ -0,0 +1,56 @@
+<!--
+https://github.com/dotnet/docs-aspire/issues/1049
+
+We are introducing support for Garnet in this PR:
+
+dotnet/aspire#4324
+
+It is presently a drop in alternative for Redis. We probably need an article that sites right alongside the Redis articles so that folks who might be looking for Redis content to understand how Garnet works can find it.
+
+The article should cover:
+
+AddGarnet
+WithDataVolume/WithBindMount
+WithPersistence
+It can probably cover off the client side pieces by just referring back to the Redis article although the Redis article might need to more clearly call out which is service code and which is app host code.
+
+Configuring Garnet using AddGarnet and using the data volume and persistence extension methods.
+
+Include links to:
+- https://github.com/microsoft/Garnet
+- https://microsoft.github.io/garnet/docs
+-->
+
+To model the Garnet resource in the app host, install the [Aspire.Hosting.Garnet](https://www.nuget.org/packages/Aspire.Hosting.Garnet) NuGet package in the [app host](xref:aspire/app-host) project.
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Aspire.Hosting.Garnet
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Aspire.Hosting.Garnet"
+                  Version="[SelectVersion]" />
+```
+
+---
+
+In your app host project, register .NET Aspire Garnet as a `GarnetResource` using the `AddGarnet` method and consume the service using the following methods:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cache = builder.AddGarnet("cache");
+
+builder.AddProject<Projects.ExampleProject>()
+       .WithReference(cache)
+```
+
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` project named `cache`. In the _:::no-loc text="Program.cs":::_ file of `ExampleProject`, the Garnet connection can be consumed using:
+
+```csharp
+builder.AddGarnet("cache");
+```

docs/caching/includes/redis-app-host.md

@@ -16,3 +16,18 @@ dotnet add package Aspire.Hosting.Redis
 ---
 
 In your app host project, register the .NET Aspire Stack Exchange Redis as a resource using the <xref:Aspire.Hosting.RedisBuilderExtensions.AddRedis%2A> method and consume the service using the following methods:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cache = builder.AddRedis("cache");
+
+builder.AddProject<Projects.ExampleProject>()
+       .WithReference(cache)
+```
+
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` project named `cache`. In the _:::no-loc text="Program.cs":::_ file of `ExampleProject`, the Redis connection can be consumed using:
+
+```csharp
+builder.AddRedis("cache");
+```

docs/caching/includes/valkey-app-host.md

@@ -0,0 +1,56 @@
+<!--
+https://github.com/dotnet/docs-aspire/issues/1049
+
+We are introducing support for Valkey in this PR:
+
+dotnet/aspire#4324
+
+It is presently a drop in alternative for Redis. We probably need an article that sites right alongside the Redis articles so that folks who might be looking for Redis content to understand how Valkey works can find it.
+
+The article should cover:
+
+AddValkey
+WithDataVolume/WithBindMount
+WithPersistence
+It can probably cover off the client side pieces by just referring back to the Redis article although the Redis article might need to more clearly call out which is service code and which is app host code.
+
+Configuring Valkey using AddValkey and using the data volume and persistence extension methods.
+
+Include links to:
+- https://github.com/valkey-io/valkey
+- https://valkey.io/docs/
+-->
+
+To model the Valkey resource in the app host, install the [Aspire.Hosting.Valkey](https://www.nuget.org/packages/Aspire.Hosting.Valkey) NuGet package in the [app host](xref:aspire/app-host) project.
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Aspire.Hosting.Valkey
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Aspire.Hosting.Valkey"
+                  Version="[SelectVersion]" />
+```
+
+---
+
+In your app host project, register the .NET Aspire Valkey as a resource using the `AddValkey` method and consume the service using the following methods:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cache = builder.AddValkey("cache");
+
+builder.AddProject<Projects.ExampleProject>()
+       .WithReference(cache)
+```
+
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` project named `cache`. In the _:::no-loc text="Program.cs":::_ file of `ExampleProject`, the Valkey connection can be consumed using:
+
+```csharp
+builder.AddValkey("cache");
+```

docs/caching/stackexchange-redis-component.md

@@ -3,6 +3,7 @@ title: .NET Aspire Stack Exchange Redis component
 description: This article describes the .NET Aspire Stack Exchange Redis component features and capabilities
 ms.topic: how-to
 ms.date: 07/17/2024
+zone_pivot_groups: resp-host
 ---
 
 # .NET Aspire Stack Exchange Redis component
@@ -49,41 +50,64 @@ public class ExampleService(IConnectionMultiplexer connectionMultiplexer)
 
 ## App host usage
 
+:::zone pivot="redis"
+
 [!INCLUDE [redis-app-host](includes/redis-app-host.md)]
 
-```csharp
-var builder = DistributedApplication.CreateBuilder(args);
+:::zone-end
+:::zone pivot="garnet"
 
-var redis = builder.AddRedis("redis");
+[!INCLUDE [garnet-app-host](includes/garnet-app-host.md)]
 
-builder.AddProject<Projects.ExampleProject>()
-       .WithReference(redis)
-```
+:::zone-end
+:::zone pivot="valkey"
 
-The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` project named `redis`. In the _:::no-loc text="Program.cs":::_ file of `ExampleProject`, the Redis connection can be consumed using:
+[!INCLUDE [valkey-app-host](includes/valkey-app-host.md)]
 
-```csharp
-builder.AddRedis("cache");
-```
+:::zone-end
 
 ## Configuration
 
 The .NET Aspire Stack Exchange Redis component 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 `builder.AddRedis`:
 
 ```csharp
-builder.AddRedis("RedisConnection");
+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 `builder.AddGarnet`:
+
+```csharp
+builder.AddGarnet("cache");
 ```
 
+:::zone-end
+:::zone pivot="valkey"
+
+[!INCLUDE [valkey-app-host](includes/valkey-app-host.md)]
+
+When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddValkey`:
+
+```csharp
+builder.AddValkey("cache");
+```
+
+:::zone-end
+
 And then the connection string will be retrieved from the `ConnectionStrings` configuration section:
 
 ```json
 {
   "ConnectionStrings": {
-    "RedisConnection": "localhost:6379"
+    "cache": "localhost:6379"
   }
 }
 ```
@@ -115,12 +139,36 @@ The .NET Aspire Stack Exchange Redis component supports <xref:Microsoft.Extensio
 
 You can also pass the `Action<StackExchangeRedisSettings>` delegate to set up some or all the options inline, for example to configure `DisableTracing`:
 
+:::zone pivot="redis"
+
 ```csharp
 builder.AddRedis(
     "cache",
     settings => settings.DisableTracing = true);
 ```
 
+:::zone-end
+:::zone pivot="garnet"
+
+```csharp
+builder.AddGarnet(
+    "cache",
+    settings => settings.DisableTracing = true);
+```
+
+:::zone-end
+:::zone pivot="valkey"
+
+[!INCLUDE [valkey-app-host](includes/valkey-app-host.md)]
+
+```csharp
+builder.AddValkey(
+    "cache",
+    settings => settings.DisableTracing = true);
+```
+
+:::zone-end
+
 [!INCLUDE [component-health-checks](../includes/component-health-checks.md)]
 
 The .NET Aspire Stack Exchange Redis component handles the following: