Content for .NET Aspire - Release 8.1

docfx.json

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

docs/app-host/withdockerfile.md

@@ -0,0 +1,105 @@
+---
+title: Add Dockerfiles to your .NET app model
+description: Learn how to add Dockerfiles to your .NET app model.
+ms.date: 07/19/2024
+---
+
+# Add Dockerfiles to your .NET app model
+
+Using .NET Aspire it is possible to specify a _Dockerfile_ to build when the apphost is started using either the <xref:Aspire.Hosting.ResourceBuilderExtensions.AddDockerfile%2A> or <xref:Aspire.Hosting.ResourceBuilderExtensions.WithDockerfile%2A> extension methods.
+
+In the example below 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 interpretted 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 is 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 vs. deployment.
+
+```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");
+```
+
+## Customizing 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 is 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();
+```
+
+## Passing 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. 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 in _Dockerfiles_. Expanding the example above, this is a mult-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: Build arguments hardcode values into the produced container image which means that the container image needs to rebuilt whenever a change is required. This is often not desirable and the use of environment variables is recommended to values that change frequently.
+
+## Passing build secrets
+
+In addition to build arguments it is 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);
+```
+
+Example of `RUN` command in Dockerfile which exposes the specified secret to the specific command:
+
+```
+# The helloworld command can read the secret from /run/secrets/ACCESS_TOKEN
+RUN --mount=type=secret,id=ACCESS_TOKEN helloworld
+```
+
+> NOTE: Caution should be used whenever secrets are handed in build environments. Common scenarios include using a token to restore dependencies from private repositories/feeds prior to a build occuring. The injected secrets should not be 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 the .NET Aspire Garnet as a resource 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: