Update AppHost eventing docs to use typed helper APIs by Copilot · Pull Request #1168 · microsoft/aspire.dev

Copilot · 2026-06-02T02:39:34Z

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
- Clarified the builder-level helper methods available for AppHost lifecycle events.
- Added API reference links for the helper surface.
- Updated the resource stopped example to use the typed helper pattern.
Related doc snippets
- Replaced legacy subscription examples with helper methods where a direct helper exists:
  - OnBeforeStart
  - OnAfterResourcesCreated
  - OnInitializeResource
  - OnConnectionStringAvailable
Release notes and examples
- Updated existing release-note and architecture snippets so they align with the current eventing guidance and preferred API shape.

// Before
builder.Eventing.Subscribe<BeforeStartEvent>((e, ct) =>
{
    return Task.CompletedTask;
});

// After
builder.OnBeforeStart((e, ct) =>
{
    return Task.CompletedTask;
});

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot

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 OnConnectionStringAvailable and reuse the same resource builder instance.
Updated the AppHost eventing page to describe helper methods, add API reference links, and include an OnResourceStopped mention/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:


+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/).


        // 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


+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;
    });


Adam Ratzman (adamint) · 2026-08-07T11:14:02Z

-        s => s with { State = KnownResourceStates.Running });
-});
+builder.AddResource(myCustom)
+    .OnInitializeResource(async (resource, e, ct) =>


OnInitializeResource first appears in release/9.4, but this is the 9.3 release page. Could you keep this example on builder.Eventing.Subscribe<InitializeResourceEvent>(...) so it remains valid for the version being documented?

Adam Ratzman (adamint) · 2026-08-07T11:14:02Z

 | `OnAfterPublish`          | `AfterPublishEvent` — raised after manifest publishing completes  |

+For the full API surface, see the [.NET
+`DistributedApplicationEventingExtensions`](https://learn.microsoft.com/dotnet/api/aspire.hosting.distributedapplicationeventingextensions)


This URL currently returns 404. We already expose the generated C# reference at /reference/api/csharp/aspire.hosting/distributedapplicationeventingextensions/; could you link that instead?

Adam Ratzman (adamint) · 2026-08-07T11:14:02Z

+builder.OnBeforeStart(async (e, ct) => { /* ... */ });
 // Run a callback once all resources have been created.
-builder.SubscribeAfterResourcesCreated(async e => { /* ... */ });
+builder.OnAfterResourcesCreated(async (e, ct) => { /* ... */ });


I don’t think OnAfterResourcesCreated exists in either release/13.3 or current Aspire; compiling this fails with CS1061. Could you keep this on builder.Eventing.Subscribe<AfterResourcesCreatedEvent>(...) and correct the matching helper row in eventing.mdx too?

Adam Ratzman (adamint)

Three docs correctness issues inline that I think should be fixed before merge: the dead .NET API link, the nonexistent OnAfterResourcesCreated helper, and a 9.4 helper on the 9.3 release page. These all look straightforward to address in place.

Initial plan

16ac317

Copilot AI assigned Copilot and David Pine (IEvangelist) Jun 2, 2026

Copilot AI linked an issue Jun 2, 2026 that may be closed by this pull request

[13.2] Update App Host Events #315

Open

Copilot started work on behalf of David Pine (IEvangelist) June 2, 2026 02:59 View session

Copilot AI and others added 2 commits June 2, 2026 03:10

Update AppHost eventing helper docs

a9c0f42

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Finalize eventing helper doc updates

8327c05

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

Copilot finished work on behalf of David Pine (IEvangelist) June 2, 2026 03:12

Copilot AI requested a review from David Pine (IEvangelist) June 2, 2026 03:12

David Pine (IEvangelist) marked this pull request as ready for review June 30, 2026 08:38

Copilot AI review requested due to automatic review settings June 30, 2026 08:38

Copilot started reviewing on behalf of David Pine (IEvangelist) June 30, 2026 08:39 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Adam Ratzman (adamint) reviewed Aug 7, 2026

View reviewed changes

Adam Ratzman (adamint) approved these changes Aug 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

Update AppHost eventing docs to use typed helper APIs - #1168

Update AppHost eventing docs to use typed helper APIs#1168
David Pine (IEvangelist) with Copilot wants to merge 3 commits into
mainfrom
copilot/132-update-app-host-events

Copilot AI commented Jun 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Uh oh!

Adam Ratzman (adamint) left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Copilot AI commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Adam Ratzman (adamint) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Adam Ratzman (adamint) left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jun 2, 2026 •

edited

Loading