Add sample Temporal integration for Aspire by cecilphillip · Pull Request #127 · temporalio/samples-dotnet

cecilphillip · 2026-02-21T15:30:17Z

What was changed

This PR adds comprehensive .NET Aspire integration for Temporal, including:

Custom Aspire resource definitions for Temporal server deployment with three deployment models:
- Local test server using Temporalio.Testing.WorkflowEnvironment
- Container-based deployment using Docker
- CLI-based server for environments without Docker
Temporal.Extensions.Aspire.Hosting library with:
- Extension methods for adding Temporal resources to Aspire applications
- Health check integration for Temporal connectivity
- Automatic service discovery and environment variable injection
- Resource lifecycle management (start/stop) via Aspire dashboard
- Configurable options for ports, namespaces, search attributes, and dynamic config
Sample Aspire application demonstrating the integration:
- TemporalioSamples.SampleAppHost - Aspire app host configuring Temporal resources
- TemporalioSamples.SampleWorker - Worker service consuming workflows/activities
- TemporalioSamples.SampleClient - Client triggering workflow execution
- TemporalioSamples.SampleWorkflow - Simple workflow and activity definitions

CLAassistant · 2026-02-21T15:30:23Z

All committers have signed the CLA.

CLAassistant · 2026-02-21T15:30:23Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

cretz · 2026-02-23T15:18:26Z

+    var connectOptions = ClientEnvConfig.LoadClientConnectOptions();
+    Console.WriteLine("\nAttempting to connect client to temporal server...");
+
+    var client = await TemporalClient.ConnectAsync(connectOptions);


Aren't you supposed to be able to use Aspire to get client connectivity information too? Even if it is powered by env vars under the hood, one might expect a type-safe Aspire way to get a client or client options for the given "temporal" reference from other project.

Aspire only does that through environment variables. There isn't anything type-safe configuration support specifically from aspire. Typically library authors would create their own using Microsoft.Extensions.Configuration bindings

I mean from a caller POV. For instance, stuff like https://aspire.dev/integrations/databases/postgres/postgres-get-started/?lang=csharp#use-the-integration-in-client-projects. I would expect that you can just put a client on the DI container w/ a single Aspire helper. Sure you can always still manually create clients.

I mean we could create an extension method that makes that a little nicer, but that would be a client specific library/package. From an aspire API perspective, they just inject configuration properties that get consumed .

They inject configuration properties for those not wanting to use the helper, but they also provide a helper. I figure the nice aspect of "Aspire helper to make server, Aspire helper to make client" is valuable even though they can use the env vars directly of course, same as Postgres there.

@cecilphillip I think what you have is idiomatic to Temporal and Aspire and what you'd want to do if a customer would actually deploy this from their Aspire setup.

@jmaeagle99 What's currently in this PR covers a hosting integration. We could also include a client integration at some point later on.

Co-authored-by: Chad Retz <chad@temporal.io>

Copilot

Pull request overview

This PR adds a new Aspire integration sample set for Temporal and introduces a Temporal.Extensions.Aspire.Hosting library that defines Temporal resources (local dev server, Docker container, and Temporal CLI) with health checks and environment variable wiring for dependent projects.

Changes:

Added an Aspire sample AppHost + client/worker + workflow projects under src/AspireIntegrations.
Introduced Temporal.Extensions.Aspire.Hosting with custom Temporal resources, options, lifecycle subscriber, and health check extensions.
Added documentation and Aspire settings for running the new sample.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
TemporalioSamples.sln	Adds the new Aspire integration projects into the solution under a new folder.
src/AspireIntegrations/TemporalioSamples.SampleWorkflow/TemporalioSamples.SampleWorkflow.csproj	New workflow project for the Aspire sample.
src/AspireIntegrations/TemporalioSamples.SampleWorkflow/SimpleWorkflow.cs	Sample workflow definition.
src/AspireIntegrations/TemporalioSamples.SampleWorkflow/SimpleActivities.cs	Sample activity definition.
src/AspireIntegrations/TemporalioSamples.SampleWorker/TemporalioSamples.SampleWorker.csproj	New worker project for the Aspire sample.
src/AspireIntegrations/TemporalioSamples.SampleWorker/Program.cs	Configures and runs a hosted Temporal worker via env-configured connectivity.
src/AspireIntegrations/TemporalioSamples.SampleClient/TemporalioSamples.SampleClient.csproj	New client project for the Aspire sample.
src/AspireIntegrations/TemporalioSamples.SampleClient/Program.cs	Connects to Temporal and starts the sample workflow.
src/AspireIntegrations/TemporalioSamples.SampleAppHost/TemporalioSamples.SampleAppHost.csproj	New Aspire AppHost project referencing the Temporal Aspire hosting library and sample projects.
src/AspireIntegrations/TemporalioSamples.SampleAppHost/Properties/launchSettings.json	Launch profiles for the AppHost.
src/AspireIntegrations/TemporalioSamples.SampleAppHost/appsettings.json	Logging configuration for AppHost.
src/AspireIntegrations/TemporalioSamples.SampleAppHost/appsettings.Development.json	Development logging configuration for AppHost.
src/AspireIntegrations/TemporalioSamples.SampleAppHost/AppHost.cs	Wires up the Temporal local dev server resource and references it from worker/client.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalResourceOptions.cs	Adds Temporal resource options layered on Temporal’s local environment options.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalResourceConstants.cs	Defines endpoint names, default ports, and image constants.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalLocalResourceSubscriber.cs	Manages local dev server lifecycle (start on init, shutdown on stop).
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalLocalResourceExtensions.cs	Adds `AddTemporalLocalDevServer`, endpoints, health checks, and dashboard commands.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalLocalResource.cs	Resource model for the local dev server.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalHealthCheckBuilderExtensions.cs	Adds health check registration helper for Temporal connectivity.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalHealthCheck.cs	Implements the Temporal connectivity health check.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalContainerResource.cs	Container-based Temporal resource + connection string expression.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalContainerOptions.cs	Container-specific options (image tag) for Temporal.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalContainerBuilderExtensions.cs	Adds Docker-based Temporal dev server resource and wiring helpers.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalCliServerResourceExtensions.cs	Adds Temporal CLI-based server resource and wiring helpers.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/TemporalCliServerResource.cs	Executable-based Temporal resource + connection string expression.
src/AspireIntegrations/Temporal.Extensions.Aspire.Hosting/Temporal.Extensions.Aspire.Hosting.csproj	New hosting library project definition and dependencies.
src/AspireIntegrations/README.md	Adds documentation for running/using the new Aspire integration and configuration options.
src/AspireIntegrations/.aspire/settings.json	Points Aspire tooling at the new AppHost project.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>


+    public new List<string> AdditionalNamespaces
+    {
+        get => additionalNamespaces.Count > 0 ? additionalNamespaces : [Namespace];
+        set => additionalNamespaces = value ?? [];


+                    if (resource.WorkflowEnvironment != null)
+                    {
+                        resourceLogger.LogInformation("Shutting down Temporal test server '{ResourceName}'...", resource.Name);
+                        await resource.WorkflowEnvironment.ShutdownAsync();
+                        resource.WorkflowEnvironment = null;
+                        resourceLogger.LogInformation("Temporal test server '{ResourceName}' shut down successfully.", resource.Name);
+                    }
+
+                    // Publish ResourceStoppedEvent to trigger subscriber cleanup and keep _environments dictionary in sync
+                    var resourceEvent = new ResourceEvent(resource, resource.Name, new CustomResourceSnapshot
+                    {
+                        ResourceType = "temporal-local",
+                        CreationTimeStamp = DateTime.UtcNow,
+                        State = KnownResourceStates.Exited,
+                        Properties = []
+                    });
+                    var stoppedEvent = new ResourceStoppedEvent(resource, context.ServiceProvider, resourceEvent);
+                    await eventing.PublishAsync(stoppedEvent, context.CancellationToken);
+


+    {
+        try
+        {
+            await TemporalClient.ConnectAsync(clientConnectOptions);


jmaeagle99 · 2026-06-10T15:55:43Z

+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>


Let's move these down to net8.0 since that is what the samples repo is currently using; I believe that is supported even with the most recent versions of Aspire.

jmaeagle99 · 2026-06-12T22:22:48Z

+
+        return builder.AddResource(resource)
+            .WithArgs(BuildContainerArgs(resource.Options))
+            .ExcludeFromManifest().WithEndpoint(


nit: put .WithEndpoint( on its own line

jmaeagle99 · 2026-06-12T22:55:55Z

+    var connectOptions = ClientEnvConfig.LoadClientConnectOptions();
+    Console.WriteLine("\nAttempting to connect client to temporal server...");
+
+    var client = await TemporalClient.ConnectAsync(connectOptions);


@cecilphillip I think what you have is idiomatic to Temporal and Aspire and what you'd want to do if a customer would actually deploy this from their Aspire setup.

jmaeagle99 · 2026-06-12T22:59:30Z

+
+// Add a worker project that depends on Temporal
+builder.AddProject<Projects.SampleWorker>("worker")
+    .WaitFor(temporal)


Should we do this automatically for them in the .WithReference calls?

that's an Apsire pattern that I've wondered about in general. It should be fine

Copilot

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 10 comments.

…sion

…rence

…dd Aspire integration tests

…ssing dashboard URLs - Switch AppHost sample from AddTemporalLocalDevServer to AddTemporalCliServer - Add TemporalCliLocator with PATH guard so AddTemporalCliServer throws immediately with an actionable error when the temporal CLI is not installed - Fix temporal-local dashboard URLs by supplying explicit port values on WithHttpEndpoint for the UI and metrics endpoints - Fix temporal-cli-server FailedToStart caused by ConnectionStringAvailableEvent callback throwing when the CLI process hasn't bound its port yet; replace with non-throwing retry loop (up to 30 x 500ms attempts) - Refactor health-check client accessor from Func<ITemporalClient?> to Func<CancellationToken, Task<ITemporalClient?>> so each probe can lazily reconnect; Unhealthy resources recover to Healthy once the server is ready without requiring a manual restart - Add 28 unit tests covering TemporalHealthCheck, TemporalHealthCheckHelper, TemporalCliLocator, TemporalResourceOptions, TemporalEnvironmentHelper, and TemporalCliServerResourceExtensions

…y guard - Add explicit port to all three WithEndpoint/WithHttpEndpoint calls in AddTemporalCliServer so the Aspire dashboard renders clickable URLs for the CLI resource (parity with local and container resources) - Add isProxied: false to all three endpoint registrations in AddTemporalDevContainer; without it Aspire's DCP proxy intercepts ports including gRPC on 7233, preventing the Temporal client from connecting and keeping the resource permanently Unhealthy - Add internal AddTemporalCliServer overload with injectable isTemporalCliAvailable seam so tests can exercise the public extension method path without depending on temporal being on the test machine PATH - Replace AddTemporalCliServer_Throws_WhenTemporalCliNotOnPath test: now calls the public extension method via builder rather than the helper directly - Add AddTemporalCliServer_RegistersExplicitPortsOnAllEndpoints regression test - Fix missing trailing newline in aspire.config.json - Switch AppHost sample to AddTemporalDevContainer

- Replace nullable 'as' casts with explicit casts for type safety - Remove conflicting VersionOverride from csproj (use central package management) - Fix StyleCop spacing violation in SimpleWorkflow - Correct README examples: AddTemporalCliServer → AddTemporalLocalDevServer - Update README project references: Projects.SampleWorker → Projects.TemporalioSamples_SampleWorker - Fix container metrics port to use constant instead of variable

Expand CLI-based deployment documentation with advanced configuration options for ports, namespaces, search attributes, and dynamic config values. This brings the CLI-based section to feature parity with Local Server and Container-based sections.

Add XML documentation comments for: - All public types (resources, extension classes, options) - All public and internal methods and properties - All method parameters and return values - All public constants with their descriptions Includes documentation for: - Resource classes (TemporalCliServerResource, TemporalContainerResource, TemporalLocalResource) - Extension methods for AddTemporalCliServer, AddTemporalDevContainer, AddTemporalLocalDevServer - Helper classes (TemporalArgsBuilder, TemporalEnvironmentHelper, TemporalHealthCheck) - Configuration classes (TemporalResourceOptions, TemporalContainerOptions) - Event subscribers and lifecycle management This addresses StyleCop rules SA1611 (missing parameter docs) and SA1615 (missing return value docs).

Add sample Temporal integration for Aspire

b5bf216

cecilphillip requested review from cretz and jmaeagle99 February 21, 2026 15:30

cecilphillip requested a review from a team as a code owner February 21, 2026 15:30

cretz reviewed Feb 23, 2026

View reviewed changes

Update src/AspireIntegrations/TemporalioSamples.SampleAppHost/AppHost.cs

d89d4bc

Co-authored-by: Chad Retz <chad@temporal.io>

cecilphillip requested a review from cretz February 23, 2026 16:16

cecilphillip added 2 commits February 23, 2026 11:19

Rename Temporal local test server

ff59b4f

Merge remote-tracking branch 'origin/cp-aspire' into cp-aspire

b45ba00

cecilphillip requested review from Copilot and removed request for cretz May 21, 2026 18:26

Copilot AI reviewed May 21, 2026

View reviewed changes

jmaeagle99 self-assigned this Jun 11, 2026

jmaeagle99 reviewed Jun 12, 2026

View reviewed changes

Merge branch 'main' into cp-aspire

cae22a7

cecilphillip requested review from Copilot and jmaeagle99 June 17, 2026 06:14

Copilot started reviewing on behalf of cecilphillip June 17, 2026 06:14 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

cecilphillip added 9 commits June 17, 2026 07:54

build: align Aspire integration projects and package/version baselines

12a9874

fix: stabilize Temporal resource options and health-check behavior

ff4cabc

refactor: consolidate Aspire integration extension helpers

344ac89

fix README method names, update Prerequisites with links and net8 ver…

fde2522

…sion

inject TEMPORAL_NAMESPACE and TEMPORAL_DEFAULT_NAMESPACE via WithRefe…

25dab66

…rence

chore: bump Aspire SDK to 13.4.4, Microsoft.Extensions.* to 10.0.8; a…

1c0a34f

…dd Aspire integration tests

replace .aspire/settings.json file with aspire.config.json

b0a250c

cecilphillip force-pushed the cp-aspire branch from f8c2286 to bba7770 Compare June 17, 2026 11:55

cecilphillip added 4 commits June 17, 2026 08:13

docs: add more XML doc strings

a49a80f

Conversation

cecilphillip commented Feb 21, 2026

What was changed

Uh oh!

CLAassistant commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Feb 21, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CLAassistant commented Feb 21, 2026 •

edited

Loading

cretz Feb 23, 2026 •

edited

Loading