Update AppHost eventing docs to use typed helper APIs#1168
Open
Copilot wants to merge 3 commits into
Open
Conversation
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Update eventing documentation for new helper events
Update AppHost eventing docs to use typed helper APIs
Jun 2, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Aspire AppHost eventing documentation and related snippets to prefer the newer typed helper APIs (for example OnBeforeStart, OnInitializeResource, OnConnectionStringAvailable) over lower-level builder.Eventing.Subscribe<T>() patterns, aligning guidance and examples with the current recommended API surface.
Changes:
- Updated release notes snippets to use
On*helper methods instead of legacy subscription APIs. - Refactored the architecture “resource examples” snippet to use
OnConnectionStringAvailableand reuse the same resource builder instance. - Updated the AppHost eventing page to describe helper methods, add API reference links, and include an
OnResourceStoppedmention/example.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| src/frontend/src/content/docs/whats-new/aspire-9-3.mdx | Updates the InitializeResource example to use .OnInitializeResource(...). |
| src/frontend/src/content/docs/whats-new/aspire-13-3.mdx | Updates C# lifecycle event snippet to use OnBeforeStart/OnAfterResourcesCreated. |
| src/frontend/src/content/docs/architecture/resource-examples.mdx | Updates connection-string capture to use .OnConnectionStringAvailable(...) and reuses redisBuilder. |
| src/frontend/src/content/docs/app-host/eventing.mdx | Clarifies helper-method guidance, adds API reference links, and updates resource-stopped example. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| </Tabs> | ||
|
|
||
| The following builder-level extension methods are available for AppHost events: | ||
| The following builder-level helper methods are available for AppHost events: |
Comment on lines
+85
to
+88
| For the full API surface, see the [.NET | ||
| `DistributedApplicationEventingExtensions`](https://learn.microsoft.com/dotnet/api/aspire.hosting.distributedapplicationeventingextensions) | ||
| API reference and the [TypeScript `Aspire.Hosting` API | ||
| reference](/reference/api/typescript/aspire.hosting/). |
Comment on lines
75
to
+77
| // 6. Add & configure container using the fluent builder pattern | ||
| // Add the RedisResource instance to the application model. | ||
| return builder.AddResource(redis) | ||
| // 6.a Expose the Redis TCP endpoint | ||
| // Map the host port (if provided) to the container's default Redis port (6379). | ||
| // Name the endpoint "tcp" for reference. | ||
| .WithEndpoint( | ||
| port: port, // Optional host port. | ||
| targetPort: 6379, // Default Redis port inside the container. | ||
| name: RedisResource.PrimaryEndpointName) // Use the constant defined in RedisResource. | ||
| // 6.b Specify container image and tag | ||
| // Define the Docker image to use for the Redis container. | ||
| .WithImage(RedisContainerImageTags.Image, RedisContainerImageTags.Tag) | ||
| // 6.c Configure container registry if needed | ||
| // Specify a container registry if the image is not on Docker Hub. | ||
| .WithImageRegistry(RedisContainerImageTags.Registry) | ||
| // 6.d Wire the health check into the resource | ||
| // Associate the previously defined health check with this resource. | ||
| // Aspire uses this for dashboard status and orchestration. | ||
| .WithHealthCheck(healthCheckKey) | ||
| // 6.e Define the container's entrypoint | ||
| // Override the default container entrypoint if necessary. Here, it's set to use shell. | ||
| .WithEntrypoint("/bin/sh") | ||
| // 6.f Pass the password ParameterResource into an environment variable | ||
| // Set environment variables for the container. This uses a callback to access | ||
| // the resource instance (`redis`) and its properties. | ||
| .WithEnvironment(context => | ||
| { | ||
| // If a password parameter exists, expose it as the REDIS_PASSWORD environment variable. | ||
| // The actual value resolution happens later via the ParameterResource. | ||
| if (redis.PasswordParameter is { } pwd) | ||
| { | ||
| context.EnvironmentVariables["REDIS_PASSWORD"] = pwd; | ||
| } | ||
| }) | ||
| // 6.g Build the container arguments lazily, preserving annotations | ||
| // Define the command-line arguments for the container. This also uses a callback | ||
| // to allow dynamic argument construction based on resource state or annotations. | ||
| .WithArgs(context => | ||
| { | ||
| // Start with the basic command to run the Redis server. | ||
| var cmd = new List<string> { "redis-server" }; | ||
|
|
||
| // If a password parameter is set, add the necessary Redis CLI arguments. | ||
| // Note: It uses the environment variable name set earlier ($REDIS_PASSWORD). | ||
| if (redis.PasswordParameter is not null) | ||
| { | ||
| cmd.Add("--requirepass"); | ||
| cmd.Add("$REDIS_PASSWORD"); // Reference the environment variable. | ||
| } | ||
|
|
||
| // Check if a PersistenceAnnotation has been added to the resource. | ||
| // Annotations allow adding optional configuration or behavior. | ||
| if (redis.TryGetLastAnnotation<PersistenceAnnotation>(out var pa)) | ||
| { | ||
| // If persistence is configured, add the corresponding Redis CLI arguments. | ||
| var interval = (pa.Interval ?? TimeSpan.FromSeconds(60)) | ||
| .TotalSeconds | ||
| .ToString(CultureInfo.InvariantCulture); | ||
| cmd.Add("--save"); | ||
| cmd.Add(interval); // Save interval in seconds. | ||
| cmd.Add(pa.KeysChangedThreshold.ToString(CultureInfo.InvariantCulture)); // Number of key changes threshold. | ||
| } | ||
|
|
||
| // Finalize the arguments for the shell entrypoint. | ||
| context.Args.Add("-c"); // Argument for /bin/sh to execute a command string. | ||
| context.Args.Add(string.Join(' ', cmd)); // Join all parts into a single command string. | ||
| return Task.CompletedTask; // Return a completed task as the callback is synchronous. | ||
| }); | ||
| return redisBuilder |
Comment on lines
+539
to
545
| cache.OnResourceStopped( | ||
| static (resource, @event, ct) => | ||
| { | ||
| logger.LogInformation("Resource {Name} stopped", @event.Resource.Name); | ||
| var logger = @event.Services.GetRequiredService<ILogger<Program>>(); | ||
| logger.LogInformation("Resource {Name} stopped", resource.Name); | ||
| return Task.CompletedTask; | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AppHost eventing docs still showed older
Eventing.Subscribe<T>patterns in places where typed helper APIs now exist. This updates the eventing guidance and related snippets to prefer the named helpers while keeping generic subscription examples only where the lower-level API is the point.AppHost eventing page
Related doc snippets
OnBeforeStartOnAfterResourcesCreatedOnInitializeResourceOnConnectionStringAvailableRelease notes and examples