Davidfowl/ts apphost

[davidfowl]

Polyglot AppHost Support: Write Aspire App Hosts in TypeScript

Overview

This PR introduces polyglot AppHost support, enabling developers to write Aspire app hosts in non-.NET languages. TypeScript is the first supported language, with the architecture designed to support additional languages (Go, Python, etc.) in the future.

This work builds on the foundational JSON-RPC infrastructure established by @sebastienros in #11667.

What's New

Developers can now create and run Aspire app hosts entirely in TypeScript:

import { createBuilder, refExpr } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder
    .addRedis("cache")
    .withRedisCommander();

const api = await builder
    .addContainer("api", "mcr.microsoft.com/dotnet/samples:aspnetapp")
    .withEnvironment("REDIS_URL", refExpr`redis://${await cache.getEndpoint("tcp")}`)
    .waitFor(cache);

await builder.build().run();

Aspire Type System (ATS)

The core innovation is the Aspire Type System (ATS) - a portable type system that maps .NET types to a unified representation any language can work with:

Concept	Description
Type ID	Portable identifier: {Assembly}/{FullTypeName}
Capability	Named operation: Aspire.Hosting.Redis/addRedis
Handle	Opaque typed reference to a .NET object
DTO	Serializable data transfer object

Integration authors expose their existing extension methods by adding [AspireExport] attributes - no wrapper code needed:

[AspireExport("addRedis", Description = "Adds a Redis resource")]
public static IResourceBuilder<RedisResource> AddRedis(
    this IDistributedApplicationBuilder builder,
    [ResourceName] string name,
    int? port = null)
{
    // Existing implementation - unchanged
}

Architecture

The CLI orchestrates two processes that communicate via JSON-RPC over Unix domain sockets:

flowchart TB
    subgraph CLI["Aspire CLI"]
        direction LR
        subgraph Guest["Guest Runtime (Node.js)"]
            direction TB
            UserCode["User Code<br/>(apphost.ts)"]
            SDK["Generated SDK<br/>(aspire.ts)"]
            ATSClient["ATS Client"]
            UserCode --> SDK --> ATSClient
        end

        subgraph Host["AppHost Server (.NET)"]
            direction TB
            Packages["Aspire.Hosting.*<br/>(Redis, etc)"]
            Dispatcher["Capability Dispatcher"]
            RPCServer["JSON-RPC Server"]
            Packages --> Dispatcher --> RPCServer
        end

        ATSClient <-->|"JSON-RPC<br/>(Unix Socket)"| RPCServer
    end

    CLI -.->|spawns| Guest
    CLI -.->|spawns| Host

Loading

Key Components

Capability Scanner (Aspire.Hosting)

• Scans assemblies for [AspireExport] attributes
• Performs 2-pass expansion: collects type hierarchy, then expands interface targets to concrete implementations
• Discovers types from parameters, return types, and callback signatures

Code Generation (Aspire.Hosting.CodeGeneration.TypeScript)

• Generates type-safe TypeScript SDK from ATS capabilities
• Produces fluent async API with thenable wrappers for single-await chains
• Handles callbacks, reference expressions, and collection wrappers

RemoteHost (Aspire.Hosting.RemoteHost)

• JSON-RPC server for guest-host communication
• Capability dispatcher routes calls to .NET implementations
• Handle registry manages object lifecycle

CLI Integration (Aspire.Cli)

• TypeScriptAppHostProject implements IAppHostProject
• Automatic SDK regeneration when packages change
• Hot reload support via nodemon

Feature Flag

Polyglot support is behind a feature flag during preview. Enable it globally:

aspire config set features.polyglotSupportEnabled true -g

CLI Commands

Once the feature flag is enabled, the --language option becomes available:

Command	Description
aspire init --language typescript	Initialize TypeScript AppHost in current directory
aspire new --language typescript	Create new project with TypeScript AppHost
aspire run	Build and run (development mode)
aspire publish	Build and run (publish mode)
aspire add <package>	Add integration package

Type System Design

ATS flattens .NET's polymorphism into a simple, portable model:

• Interface inheritance → Expanded to concrete types at scan time
• Generic constraints → Resolved to concrete types at scan time
• Method overloading → Not supported (method names must be unique per target type)

Each concrete type gets a complete list of capabilities - no type hierarchy to reason about in guest languages.

Generated TypeScript Features

• Fluent async chaining: await builder.addRedis("cache").withRedisCommander()
• Reference expressions: refExpr`redis://${endpoint}`
• Typed callbacks: withEnvironmentCallback(async (ctx) => { ... })
• Collection wrappers: AspireDict<K,V> and AspireList<T> for mutable .NET collections
• Automatic handle wrapping: Callback parameters receive typed wrapper classes

Security

Both guest and host run locally, started by the CLI:

• Capability allowlist (only [AspireExport] methods callable)
• Socket authentication with secret token
• Unix socket permissions (owner-only)
• DTO enforcement (only [AspireDto] types serialized)

Documentation

See docs/specs/polyglot-apphost.md for complete specification including:

• Wire protocol details
• Type mapping tables
• Code generation architecture
• Guide for adding new languages

Testing

• Unit tests for capability scanning and type expansion
• Snapshot tests for generated TypeScript code
• Integration tests with TypeScript playground

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13705

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13705"

[sebastienros]

Is this folder supposed to be tracked? The cli is still required to start the apphost so it would still be re-generated if not.

[sebastienros]

Reasons to keep it: detect changes when updating codegen, see what it looks like (same as manifest files)

[sebastienros]

Is it really a resolution or a requirement on the library authors? What about something that the app host dev could specify in an options file, could even rename anything even if there aren't any conflicts.

[sebastienros]

Then next level of option is to be able to aspire-import any method that might not be exported by default. (kind of private reflection).

[sebastienros]

... unique to the apphost project location

[sebastienros]

Is guest runtime the official name? No "App Host" something

[davidfowl]

Yes apphost sever and guest

[sebastienros]

Should it be renamed to match the name "App Host Server" instead of "remote"?

[sebastienros]

Will check. Are handles strings (unique)?

[davidfowl]

They are ints today but will probably need to change that (overflow), the handle is is unique.

[sebastienros]

Should guest runtimes have hooks/events/filters to be able to alter the messages?

[davidfowl]

When we need it we can add it. What scenario are you thinking ?

[sebastienros]

Do we have a command to list the capabilities of a specific project? Might be useful for API reviews and detect breaking changes. Or even debugging.

[davidfowl]

I’m not sure that’s useful for anyone but us so not a command but something we can do in debug mode

[sebastienros]

Do we need a doc format for things like see cref but using ATS? Are parameters documented?

[davidfowl]

Yea likely

[sebastienros]

Is it really an Error or more precisely it should be a handle that is sent (otherwise error)

[Meir017]

Looks really cool, is this a similar pattern to how playwright supports multiple languages?

[davidfowl]

Looks really cool, is this a similar pattern to how playwright supports multiple languages?

I didn't look at playwright. @sebastienros and I built several prototypes over the last year, and this is the approach we liked best.

[Meir017]

Looks really cool, is this a similar pattern to how playwright supports multiple languages?

I didn't look at playwright. @sebastienros and I built several prototypes over the last year, and this is the approach we liked best.

FYI @pavelfeldman

[sebastienros]

@Meir017 your comment got me curious so I investigated as I had never actually looked at how playwright works.

• Playright client SDKs start a node process they own and communicate with it using JSON-RPC over stdio. It accepts parallel commands (they are made serial by the SDK).
• The client sdks generation is driven by the communication protocol and api specifications.
• The node app owns the Chrome/CDP interop.

Key differences:

• Aspire sdks specification is extracted from the nuget packages using reflection. But first in a intermediate model, kind of like the api specification of playwright.
• The aspire is a shared process so communication is using a network stream instead of stdio.
• Aspire's API surface is not stable as integrations can be imported, whereas Playwright has a stable api.json for the client sdks to store the shape of the API.

Disclaimer: based on my (and ChatGPT's) understanding of playwright