Add multi-language integrations guide by davidfowl · Pull Request #558 · microsoft/aspire.dev

davidfowl · 2026-03-19T14:10:57Z

Summary

New documentation for integration authors explaining how to make their Aspire hosting integrations work with TypeScript AppHosts and other non-.NET app hosts.

Relates to dotnet/aspire#14069 (Part 4: Extensibility for Integration Authors)

Changes

New doc: extensibility/multi-language-integration-authoring.mdx covering:
- [AspireExport] on extension methods and resource types
- [AspireDto] for configuration objects
- [AspireExportIgnore] for incompatible overloads
- [AspireUnion] for multi-type parameters
- Analyzer package (Aspire.Hosting.Integration.Analyzers) with all 10 diagnostic rules (ASPIREEXPORT001–010)
- Third-party integration support (copy attributes, no package dependency needed)
- Local development with project references in aspire.config.json (from Add project reference support for polyglot apphost integrations aspire#14821)
- Testing workflow, supported types reference
Sidebar entry added under Extensibility section

Testing

Verified page renders correctly on Astro dev server via playwright-cli
All sections, code blocks, tables, tabs, and links confirmed working
E2E validated: Created a custom integration with [AspireExport], referenced it via .csproj path in a TypeScript AppHost, confirmed SDK generation and resource startup (test project at /tmp/aspire-projref-e2e/)

New doc explaining how integration authors export their APIs for TypeScript AppHosts using [AspireExport], [AspireDto], [AspireExportIgnore], and [AspireUnion] attributes. Covers the analyzer (ASPIREEXPORT001-010), local development with project references in aspire.config.json, third-party attribute definitions, and a supported types reference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

IEvangelist

Great start! I have several questions, nits, and suggestions.

IEvangelist · 2026-03-19T14:42:44Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

+</PackageReference>
+```
+
+The analyzer reports 10 diagnostics (ASPIREEXPORT001–010) that help you get your exports right before users encounter runtime errors.


I don't think we should explicitly call out the number of diagnostics, as that's fragile. Instead, say more generically that there are a number of diagnostics available, and perhaps detail some of the common scenarios these diagnostics cover/handle.

We'll also need to add these diagnostic articles to the existing /diagnostics/overview/ and create a new article per diagnostic following the existing patterns.

It also seems like we need a ASPIREATS001 diag article too.

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

IEvangelist · 2026-03-19T14:49:16Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

Since this arrticle falls under the extensibility node in the sidebar, we should link to it from the other TypeScript AppHost articles.

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

IEvangelist · 2026-03-19T14:54:21Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

+    // Your existing implementation...
+}
+
+[AspireExport]


We should have an example that uses ExposeMethods and ExposeProperties set to true, detailing what they are/what they do and when to use them. In fact, there are several other properties on this attribute that should be detailed.

Most resources should have ExportProperties = true

IEvangelist · 2026-03-19T14:58:16Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

+
+## Third-party integrations
+
+If your integration doesn't reference `Aspire.Hosting` directly (or you want to avoid a version dependency on the attribute types), you can define your own copies of the ATS attributes. The scanner discovers attributes by **full type name**, not by assembly reference.


Curious about this, how can you be an Aspire hosting integration without depending on Aspire.Hosting? Also, if this is such a concern - why not leave the abstractions, attributes, etc. in their own separate assembly?

Yea, tbh this isn't interesting to add, it's an implementation detail.

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

Co-authored-by: David Pine <david.pine@microsoft.com>

…language integration authoring guide

IEvangelist · 2026-03-19T15:18:39Z

Hey @copilot, could you please update this PR to include new articles for the missing diagnostics that are called out?

Copilot · 2026-03-19T15:18:48Z

@IEvangelist I've opened a new pull request, #560, to work on those changes. Once the pull request is ready, I'll request review from you.

sebastienros · 2026-03-19T15:20:22Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

+Add `[AspireExport]` to your `Add*`, `With*`, and `Run*` extension methods. The attribute takes a method name that becomes the TypeScript API:
+
+```csharp title="C# — MyDatabaseBuilderExtensions.cs"
+#pragma warning disable ASPIREATS001 // ATS types are experimental


Maybe suggest to discard this warning in the csproj?

sebastienros · 2026-03-19T15:27:58Z

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

+| **Special**     | `ParameterResource`, `ReferenceExpression`, `EndpointReference`, `CancellationToken`                 |
+| **Nullable**    | Any of the above as nullable (`T?`)                                                                  |
+
+Types that are **not** ATS-compatible include: `Action<T>`, `Func<T>`, `IConfiguration`, `ILogger` (unless explicitly exported), interpolated string handlers, and custom complex types without `[AspireExport]` or `[AspireDto]`.


Isn't that mostly wrong statements?

Most delegates are compatible. ILogger and even IServiceProvider are already exported. We might have some exports today that were not because of these, but we'll revisit them in 13.2.1 or 13.3 because in the meantime it has been aded.

Also Action maybe require the RunAsBackgroundSoemthing when it's invoked inline (and not referenced as a later callback)

- Don't hardcode diagnostic count, describe scenarios generically - Show NoWarn in csproj instead of #pragma for ASPIREATS001 - Add ExposeProperties/ExposeMethods examples (per sebastienros) - Fix supported types: delegates, ILogger, IServiceProvider are compatible - Remove Third-party integrations section (implementation detail per davidfowl) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…tegrations Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

davidfowl requested a review from IEvangelist as a code owner March 19, 2026 14:10

Shorten sidebar label to 'Integration exports'

8b3d490

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

davidfowl force-pushed the multi-language-authoring branch from ce9223b to 8b3d490 Compare March 19, 2026 14:21

davidfowl changed the title ~~Add multi-language integration authoring guide~~ Add multi-language integrations guide Mar 19, 2026

davidfowl and others added 2 commits March 19, 2026 10:22

Rename title to 'Multi-language integrations'

655586e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove 'non-.NET' phrasing from integration authoring doc

aa50e70

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

IEvangelist approved these changes Mar 19, 2026

View reviewed changes

IEvangelist reviewed Mar 19, 2026

View reviewed changes

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx Outdated Show resolved Hide resolved

IEvangelist added 2 commits March 19, 2026 10:11

Apply suggestions from code review

c5e28b8

Co-authored-by: David Pine <david.pine@microsoft.com>

Refactor code formatting and improve TypeScript SDK example in multi-…

dcc3424

…language integration authoring guide

Copilot AI mentioned this pull request Mar 19, 2026

[WIP] Add multi-language integrations guide #560

Closed

sebastienros reviewed Mar 19, 2026

View reviewed changes

davidfowl and others added 2 commits March 19, 2026 11:55

Add cross-links from TypeScript AppHost articles to multi-language in…

46d292f

…tegrations Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

IEvangelist merged commit 9887940 into release/13.2 Mar 19, 2026
1 check passed

IEvangelist deleted the multi-language-authoring branch March 19, 2026 16:03


		## Third-party integrations

		If your integration doesn't reference `Aspire.Hosting` directly (or you want to avoid a version dependency on the attribute types), you can define your own copies of the ATS attributes. The scanner discovers attributes by full type name, not by assembly reference.

Conversation

davidfowl commented Mar 19, 2026

Summary

Changes

Testing

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

IEvangelist Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

IEvangelist Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

IEvangelist Mar 19, 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!

sebastienros Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

IEvangelist Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

davidfowl Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

IEvangelist commented Mar 19, 2026

Uh oh!

Copilot AI commented Mar 19, 2026

Uh oh!

sebastienros Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

sebastienros Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

IEvangelist Mar 19, 2026 •

edited

Loading