microsoft / microsoft/aspire

Complete polyglot integration host support and cross-language integration exports

Open
#16,220 5 comments 0 reactions 1 assignee Claimed by @sebastienros View on GitHub
area-polyglot
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

**Spike branch:** [`davidfowl/ts-integration`](https://github.com/microsoft/aspire/tree/davidfowl/ts-integration) (`bb3cd1289`)

This issue tracks the follow-up work after the polyglot integration host spike.

The spike proved that Aspire can support integrations authored in TypeScript and other guest languages, and project them into guest AppHosts as first-class generated APIs. In particular, it established an end-to-end path where:

- the CLI resolves integration references from `aspire.config.json`
- guest-language integration dependencies are restored before startup
- the CLI writes integration host entries into the generated AppHost server config
- the AppHost server owns integration host lifetime
- the AppHost server gathers capabilities from external hosts and merges them into ATS/codegen
- runtime calls are dispatched back to the owning integration over JSON-RPC
- TypeScript integrations can opt into projection via `AspireExport(...)` and `defineIntegration(...)`

The spike also added the supporting design docs and playgrounds for this model:
- `docs/specs/polyglot-integrations.md`
- `docs/specs/polyglot-apphost.md`
- `playground/TsIntegrationSpike`
- `playground/TsKafkaLib`

## What the spike established

At a design level, the winning model is:

- integrations are authored as normal language-native packages on top of generated Aspire hosting APIs
- unannotated integrations remain same-language free-function libraries
- annotated integrations are exported through a common capability schema
- the AppHost server owns integration lifetime uniformly across in-proc .NET integrations and out-of-proc hosts
- generated guest SDKs project exported capabilities into fluent builder methods regardless of consumer language

## Architecture direction

The spike should move toward a more uniform end-state than the current split between “in-proc .NET integrations” and “external integration hosts”.

The intended model is:

![Image](https://github.com/user-attachments/assets/791f1f1a-767d-4505-a0f0-62c8bf8b8495)

- the AppHost server is the control plane for composition and integration dispatch
- the CLI, VS Code extension, and AppHost are clients around that server boundary
- DCP is a backend the AppHost server talks to over HTTP, not part of the integration model itself
- ATS and the generated Aspire hosting surface become the shared integration contract and standard library, rather than `Aspire.Hosting.dll` being the defining boundary
- every integration, including C# integrations, should converge on the same capability boundary

Long term, C# should move toward being just another integration host from the architectural point of view, even if the implementation keeps an in-proc path as a compatibility mechanism or optimization. In other words, in-proc assembly loading may remain an implementation detail, but it should not be the model the rest of the system is built around.

This also implies two primary RPC seams:

1. AppHost ↔ AppHost server
2. AppHost server ↔ integration hosts

That direction is broader than “polyglot support”. It is a move toward a uniform server-owned integration architecture where language becomes an implementation detail rather than the shape of the system.

## What is still missing

This is still a spike, not a finished feature. The biggest gaps are:

- only `typescript/nodejs` currently hosts integrations end-to-end
- TypeScript projection metadata is still hand-authored
- external integrations cannot yet contribute handle/DTO catalogs beyond existing ATS knowledge
- `aspire sdk dump` / `aspire sdk generate` still assume `.csproj` input
- `aspire add` is still NuGet-centric and has no per-language registry story
- diagnostics need more polish for partially supported or misconfigured integrations
- end-to-end automated coverage for multi-host / multi-language projection scenarios is still limited
- the current implementation still treats .NET integrations and guest-language integration hosts as different architectural shapes rather than different implementations of the same abstraction

## Proposed follow-up work

1. Productize the TypeScript authoring story
- emit generated type-ref constants so authors do not hand-write projection type refs
- move toward signature/projection inference so metadata duplication is minimized

2. Validate the model with a second hosted language
- add `ILanguageSupport.GetIntegrationHostSpec()` for another language, likely Python
- run the same projection/dispatch flow end-to-end

3. Improve CLI ergonomics for guest-language integration authors
- allow SDK dump/generate flows for guest-language integrations
- add a language-extensible package discovery/add story

4. Extend runtime projection
- allow external integrations to contribute handles and DTOs
- add stronger metadata validation and better failure diagnostics

5. Converge on a single integration-host abstraction
- treat the AppHost server as the single owner of integration lifetime and dispatch
- make .NET and guest-language integrations different implementations of the same model
- preserve in-proc loading only as an optimization or compatibility path, not as the architectural center of gravity

6. Add dedicated automated coverage
- multi-host projection
- cross-language capability projection
- runtime dispatch and callback flow
- startup / registration failure cases
- mixed scenarios involving both C# and guest-language integrations under the same server-owned model

## Exit criteria

We should consider this area productized when:

- at least two guest languages can host integrations end-to-end
- TypeScript integrations no longer require hand-written projection type refs
- guest-language integration authors can inspect/generate SDK output with normal CLI flows
- `aspire add` has a language-extensible registry model
- external integrations can contribute more than capability metadata
- there is solid E2E coverage for external capability projection and dispatch
- the AppHost server is clearly the uniform control plane for integration lifetime and dispatch
- .NET and guest-language integrations fit the same architectural abstraction, even if they do not use the same transport implementation internally
- failure modes produce actionable diagnostics

## Related issues

- #15119

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.