Add extensibility article on how to write non-container custom resources #3850

Copilot · 2025-06-18T16:35:43Z

This PR adds a new documentation article that explains how to create custom .NET Aspire resources that don't rely on containers, addressing the need for guidance on non-container extensibility patterns.

What's Added

New article: docs/extensibility/custom-non-container-resource.md - Comprehensive guide on creating non-container custom resources
Working code example: HTTP proxy resource demonstrating lifecycle hooks and dashboard integration
Supporting snippets: Complete, buildable code samples in docs/extensibility/snippets/HttpProxyResource/
Updated navigation: Added the new article to the table of contents and cross-referenced from existing articles

Key Content

The article covers:

When to use non-container resources vs simpler approaches like AddConnectionString() or AddParameter()
Core implementation patterns using IResource, IResourceWithEndpoints, and extension methods
Lifecycle management with IDistributedApplicationLifecycleHook for startup/shutdown coordination
Dashboard integration through standard .NET logging and notes on advanced notification services
Practical example with an in-process HTTP proxy that demonstrates all concepts

Example Usage

var builder = DistributedApplication.CreateBuilder(args);

// Add a non-container HTTP proxy resource
var proxy = builder.AddHttpProxy("api-proxy", "https://jsonplaceholder.typicode.com");

var webapp = builder.AddProject<Projects.WebApp>("webapp")
                    .WithReference(proxy);

builder.Build().Run();

The implementation shows how to:

Hook into application lifecycle events
Manage background services and cleanup
Integrate with the Aspire dashboard through logging
Provide meaningful status updates to developers

Fixes #792.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Internal previews

📄 File	🔗 Preview link
docs/extensibility/custom-non-container-resource.md	docs/extensibility/custom-non-container-resource
docs/toc.yml	docs/toc

Co-authored-by: IEvangelist <[email protected]>

…icles Co-authored-by: IEvangelist <[email protected]>

IEvangelist · 2025-06-25T19:45:35Z

docs/extensibility/snippets/HttpProxyResource/HttpProxySample.AppHost/Program.cs

Hey @copilot - this Program.cs file alone will not work without .NET 10, instead you need to include a .csproj for the Aspire app host, and likely a solution (I prefer the .slnx format) that points to the hosting and app host projects.

Added the missing .csproj file for the AppHost project and a .slnx solution file that references both projects. The AppHost now has proper project structure with .NET 9 target framework and latest Aspire package versions. (2fba711)

IEvangelist · 2025-06-25T19:46:30Z

docs/extensibility/snippets/HttpProxyResource/HttpProxy.Hosting/HttpProxy.Hosting.csproj

+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" Version="8.0.0" />


Let's use the latest version.

Suggested change

<PackageReference Include="Aspire.Hosting" Version="8.0.0" />

<PackageReference Include="Aspire.Hosting" Version="9.3.2" />

Updated to use Aspire.Hosting version 9.3.1. (2fba711)

IEvangelist · 2025-06-25T19:46:42Z

docs/extensibility/snippets/HttpProxyResource/HttpProxy.Hosting/HttpProxy.Hosting.csproj

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


Let's use .NET 9.

Suggested change

<TargetFramework>net8.0</TargetFramework>

<TargetFramework>net9.0</TargetFramework>

Updated target framework to net9.0. (2fba711)

IEvangelist · 2025-06-25T19:46:54Z

docs/extensibility/custom-non-container-resource.md

+1. **Resource cleanup**: Always implement proper disposal in lifecycle hooks
+2. **Error handling**: Catch and log exceptions, update status appropriately  
+3. **Status updates**: Provide meaningful status information to users
+4. **Performance**: Avoid blocking operations in lifecycle methods
+5. **Dependencies**: Use dependency injection for required services


Suggested change

1. **Resource cleanup**: Always implement proper disposal in lifecycle hooks

2. **Error handling**: Catch and log exceptions, update status appropriately

3. **Status updates**: Provide meaningful status information to users

4. **Performance**: Avoid blocking operations in lifecycle methods

5. **Dependencies**: Use dependency injection for required services

1. **Resource cleanup**: Always implement proper disposal in lifecycle hooks

1. **Error handling**: Catch and log exceptions, update status appropriately

1. **Status updates**: Provide meaningful status information to users

1. **Performance**: Avoid blocking operations in lifecycle methods

1. **Dependencies**: Use dependency injection for required services

Fixed the numbered list formatting to use "1." for all items as per the style guide. (2fba711)

IEvangelist · 2025-06-25T19:50:14Z

docs/extensibility/custom-non-container-resource.md

+
+For more sophisticated dashboard integration, you can use:
+
+- **Status notifications**: Update resource state and properties in real-time


We should include links to these features, and how to implement them. I think we do have docs on some of those.

Added links to health checks documentation and dashboard exploration guide in the advanced dashboard features section. (2fba711)

IEvangelist · 2025-06-25T19:52:41Z

docs/extensibility/custom-non-container-resource.md

+---
+title: Create non-container custom resources
+description: Learn how to create custom .NET Aspire resources that don't rely on containers using lifecycle hooks and dashboard integration.
+ms.date: 06/18/2025


Suggested change

ms.date: 06/18/2025

ms.date: 06/25/2025

Updated ms.date to 06/25/2025. (2fba711)

IEvangelist · 2025-06-25T19:52:50Z

docs/extensibility/custom-non-container-resource.md

+
+## Dashboard integration
+
+The resource integrates with the Aspire dashboard through:


I'm not a fan of this, it's an opening statement that's terminated with the :. I was expecting a diagram, bullet list, or something... it took me a bit to realize that it was intended to be the subsections. I'd prefer strong details about the dashboard integration.

Rewrote the dashboard integration section with stronger details about how non-container resources integrate with the dashboard, removed the colon-terminated opening statement, and provided more concrete information about the integration channels. (2fba711)

IEvangelist · 2025-06-25T19:54:17Z

docs/extensibility/custom-hosting-integration.md

+> [!div class="nextstepaction"]
+> [Create non-container custom resources](custom-non-container-resource.md)


I wouldn't consider this really a next step, it's more like an alternative approach. I'd consider removing this link here.

Removed the link to non-container custom resources from the next steps section as it's more of an alternative approach than a continuation. (2fba711)

IEvangelist · 2025-06-25T19:55:39Z

docs/extensibility/custom-non-container-resource.md

+The extension method automatically registers the lifecycle hook:
+
+```csharp
+public static IResourceBuilder<HttpProxyResource> AddHttpProxy(


This code block should instead use the :::code syntax instead to pull in the HttpProxyResourceBuilderExtensions.cs file.

Replaced the inline code block with :::code syntax to reference the HttpProxyResourceBuilderExtensions.cs file directly. (2fba711)

IEvangelist · 2025-06-25T19:57:37Z

docs/toc.yml

@@ -378,6 +378,9 @@ items:
  - name: Create hosting integrations
    displayName: resources,extensibility,hosting,integrations
    href: extensibility/custom-hosting-integration.md
+  - name: Create non-container custom resources


The original three articles here were delivered as a set, continuing on the previous content. Adding this one here makes this set disjointed, instead it might be better to have this under the Custom resources area in the TOC.

Moved the non-container custom resources article to a new "Custom resources" section in the TOC, separating it from the original three custom integration articles to avoid making them disjointed. (2fba711)

…ove docs structure Co-authored-by: IEvangelist <[email protected]>

IEvangelist · 2025-06-26T19:35:14Z

docs/extensibility/snippets/HttpProxyResource/HttpProxySample.slnx

This is invalid .slnx syntax. If you're not familiar with it, here's an example from one of my personal projects to learn from:

<Solution> <Folder Name="/playground/"> <Project Path="playground/ProfanityFilter.Api/ProfanityFilter.Api.csproj" /> <Project Path="playground/ProfanityFilter.AppHost/ProfanityFilter.AppHost.csproj" /> </Folder> <Folder Name="/Solution Items/"> <File Path=".dockerignore" /> <File Path=".editorconfig" /> <File Path=".github/workflows/dogfood.yml" /> <File Path=".github/workflows/dotnet.yml" /> <File Path=".github/workflows/release-api.yml" /> <File Path=".github/workflows/release-nuget.yml" /> <File Path=".github/workflows/release.yml" /> <File Path="action.yml" /> <File Path="Directory.Build.props" /> <File Path="Directory.Packages.props" /> <File Path="global.json" /> <File Path="LICENSE" /> <File Path="README.md" /> </Folder> <Folder Name="/src/"> <Project Path="src/ProfanityFilter.Action/ProfanityFilter.Action.csproj" /> <Project Path="src/ProfanityFilter.Client/ProfanityFilter.Client.csproj" /> <Project Path="src/ProfanityFilter.Common/ProfanityFilter.Common.csproj" /> <Project Path="src/ProfanityFilter.Hosting/ProfanityFilter.Hosting.csproj" /> <Project Path="src/ProfanityFilter.Services/ProfanityFilter.Services.csproj" /> <Project Path="src/ProfanityFilter.WebApi/ProfanityFilter.WebApi.csproj" /> </Folder> <Folder Name="/tests/"> <Project Path="tests/ProfanityFilter.Action.Tests/ProfanityFilter.Action.Tests.csproj" /> <Project Path="tests/ProfanityFilter.Client.Tests/ProfanityFilter.Client.Tests.csproj" /> <Project Path="tests/ProfanityFilter.Common.Tests/ProfanityFilter.Common.Tests.csproj" /> <Project Path="tests/ProfanityFilter.Services.Tests/ProfanityFilter.Services.Tests.csproj" /> </Folder> </Solution>

Fixed the .slnx file syntax by converting from invalid JSON format to proper XML format with ProjectReference elements. (192c993)

IEvangelist · 2025-06-26T19:42:14Z

docs/toc.yml

+- name: Custom resources
+  items:
+  - name: Create non-container custom resources
+    displayName: resources,extensibility,hosting,integrations,lifecycle,dashboard
+    href: extensibility/custom-non-container-resource.md


I can see why this is confusing, and I admit...I wasn't very clear. Let's instead move this under Dev-time orchestration node instead. It can be a top-level node under that.

Moved the custom resources section under the Dev-time orchestration node as a top-level item, after "Persist data using volumes". (192c993)

…section Co-authored-by: IEvangelist <[email protected]>

IEvangelist

We need complete sentences with proper punctuation for all bullet points.

IEvangelist · 2025-06-26T19:49:50Z

docs/extensibility/snippets/HttpProxyResource/HttpProxySample.slnx

+<Project>
+  <Sdk Name="Microsoft.Build.Traversal" />
+  <ProjectReference Include="HttpProxy.Hosting/HttpProxy.Hosting.csproj" />
+  <ProjectReference Include="HttpProxySample.AppHost/HttpProxySample.AppHost.csproj" />
+</Project>


Suggested change

<Project>

<Sdk Name="Microsoft.Build.Traversal" />

<ProjectReference Include="HttpProxy.Hosting/HttpProxy.Hosting.csproj" />

<ProjectReference Include="HttpProxySample.AppHost/HttpProxySample.AppHost.csproj" />

</Project>

<Solution>

<Folder Name="/src/">

<Project Path="HttpProxy.Hosting/HttpProxy.Hosting.csproj" />

<Project Path="HttpProxySample.AppHost/HttpProxySample.AppHost.csproj" />

</Folder>

</Solution>

Fixed the .slnx syntax to use proper XML format with folder structure and project elements as suggested. (18f672b)

IEvangelist · 2025-06-26T19:50:11Z

docs/toc.yml

+  - name: Custom resources
+    items:
+    - name: Create non-container custom resources
+      displayName: resources,extensibility,hosting,integrations,lifecycle,dashboard
+      href: extensibility/custom-non-container-resource.md


Suggested change

- name: Custom resources

items:

- name: Create non-container custom resources

displayName: resources,extensibility,hosting,integrations,lifecycle,dashboard

href: extensibility/custom-non-container-resource.md

- name: Create non-container custom resources

displayName: resources,extensibility,hosting,integrations,lifecycle,dashboard

href: extensibility/custom-non-container-resource.md

Updated the TOC entry formatting for the custom resources article as suggested. (18f672b)

IEvangelist · 2025-06-26T19:50:23Z

docs/toc.yml

@@ -373,6 +378,7 @@ items:
  - name: Aspire.Hosting API reference
    href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.3&preserve-view=true

+


Suggested change

Removed the empty line from the TOC as suggested. (18f672b)

Co-authored-by: IEvangelist <[email protected]>

Copilot · 2025-06-26T19:54:33Z

We need complete sentences with proper punctuation for all bullet points.

Fixed all bullet points to use complete sentences with proper punctuation throughout the document. (18f672b)

Initial plan for issue

ae7651e

Copilot AI assigned Copilot and IEvangelist Jun 18, 2025

Copilot started work on behalf of IEvangelist June 18, 2025 16:35 View session

Copilot AI and others added 2 commits June 18, 2025 16:45

Add non-container custom resource article with lifecycle hooks example

944bda3

Co-authored-by: IEvangelist <[email protected]>

Add cross-references and improve navigation between extensibility art…

6ea8f13

…icles Co-authored-by: IEvangelist <[email protected]>

Copilot AI changed the title ~~[WIP] Add extensiblity article on how to write a non container based custom resource~~ Add extensibility article on how to write non-container custom resources Jun 18, 2025

Copilot AI requested a review from IEvangelist June 18, 2025 16:47

Copilot finished work on behalf of IEvangelist June 18, 2025 16:47

IEvangelist requested changes Jun 25, 2025

View reviewed changes

Copilot started work on behalf of IEvangelist June 25, 2025 19:57 View session

Address PR feedback: Add missing project files, update versions, impr…

2fba711

…ove docs structure Co-authored-by: IEvangelist <[email protected]>

Copilot AI requested a review from IEvangelist June 25, 2025 20:03

Copilot finished work on behalf of IEvangelist June 25, 2025 20:03

IEvangelist requested changes Jun 26, 2025

View reviewed changes

Copilot started work on behalf of IEvangelist June 26, 2025 19:42 View session

Fix .slnx syntax and move custom resources to Dev-time orchestration …

192c993

…section Co-authored-by: IEvangelist <[email protected]>

Copilot finished work on behalf of IEvangelist June 26, 2025 19:46

Copilot AI requested a review from IEvangelist June 26, 2025 19:46

IEvangelist requested changes Jun 26, 2025

View reviewed changes

Copilot started work on behalf of IEvangelist June 26, 2025 19:50 View session

Fix bullet points, .slnx syntax, and TOC formatting based on PR feedback

18f672b

Co-authored-by: IEvangelist <[email protected]>

Copilot finished work on behalf of IEvangelist June 26, 2025 19:55

Copilot AI requested a review from IEvangelist June 26, 2025 19:55

	<PackageReference Include="Aspire.Hosting" Version="8.0.0" />
	<PackageReference Include="Aspire.Hosting" Version="9.3.2" />

	<TargetFramework>net8.0</TargetFramework>
	<TargetFramework>net9.0</TargetFramework>


		For more sophisticated dashboard integration, you can use:

		- Status notifications: Update resource state and properties in real-time


		## Dashboard integration

		The resource integrates with the Aspire dashboard through:

		> [!div class="nextstepaction"]
		> [Create non-container custom resources](custom-non-container-resource.md)

-<Project>
-  <Sdk Name="Microsoft.Build.Traversal" />
-  <ProjectReference Include="HttpProxy.Hosting/HttpProxy.Hosting.csproj" />
-  <ProjectReference Include="HttpProxySample.AppHost/HttpProxySample.AppHost.csproj" />
-</Project>
+<Solution>
+      <Folder Name="/src/">
+    <Project Path="HttpProxy.Hosting/HttpProxy.Hosting.csproj" />
+    <Project Path="HttpProxySample.AppHost/HttpProxySample.AppHost.csproj" />
+  </Folder>
+</Solution>

		@@ -373,6 +378,7 @@ items:
		- name: Aspire.Hosting API reference
		href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.3&preserve-view=true

Add extensibility article on how to write non-container custom resources #3850

Are you sure you want to change the base?

Add extensibility article on how to write non-container custom resources #3850

Conversation

Copilot AI commented Jun 18, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's Added

Key Content

Example Usage

Internal previews

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Copilot AI commented Jun 18, 2025 •

edited by github-actions bot

Loading