Document ATS support in custom integration guides

[David Pine (IEvangelist)]

Summary

• explain how custom hosting integrations opt into Aspire Type System (ATS) generation
• add C# and TypeScript AppHost examples to the existing MailDev tutorials
• link the guides to the runnable MailDev and MailKit sample
• update the tutorial to Aspire 13.5 and patched MailKit/OpenTelemetry package versions

Related sample: microsoft/aspire-samples#1891

Validation

• all three edited MDX files pass Prettier
• git diff whitespace validation passes
• generated TypeScript signatures were validated against Aspire 13.5 ATS output

[Copilot]

Pull request overview

Updates the custom integration documentation to explain how hosting integrations opt into Aspire Type System (ATS) export/TypeScript projection, and adds cross-language (C#/TypeScript) AppHost guidance and sample links using the MailDev/MailKit tutorials as the running example.

Changes:

• Document ATS export requirements ([AspireExport]) and add links to the runnable MailDev/MailKit sample.
• Add TypeScript AppHost examples alongside existing C# AppHost examples via <Tabs>.
• Refresh tutorial content to Aspire 13.5 and updated package versions where referenced.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
src/frontend/src/content/docs/integrations/custom-integrations/secure-communication.mdx	Adds sample link + ATS context and introduces C#/TypeScript AppHost tabs for the secure-credentials flow.
src/frontend/src/content/docs/integrations/custom-integrations/hosting-integrations.mdx	Documents ATS export via [AspireExport], adds runnable sample link, and adds C#/TypeScript AppHost tabs; updates Aspire version references.
src/frontend/src/content/docs/integrations/custom-integrations/client-integrations.mdx	Adds ATS clarification + sample link, updates referenced package versions, and adjusts tutorial formatting/screenshots.

Suppressed comments (3)

src/frontend/src/content/docs/integrations/custom-integrations/hosting-integrations.mdx:64

• This block combines steps 1 and 2 into a single line, which will render as one step instead of two. Split the numbered items onto separate lines so each step is distinct.

<Steps>
  1. A custom resource type that implements `IResource` 2. An extension method
  for `IDistributedApplicationBuilder` named `Add{CustomResource}` where `
  {CustomResource}` is the name of the custom resource.
</Steps>

src/frontend/src/content/docs/integrations/custom-integrations/secure-communication.mdx:210

• The TypeScript tab’s fenced code is indented, which can prevent Markdown/MDX from recognizing it as a fenced block. De-indenting the content and keeping fences near the left margin should make the snippet render reliably.

    <TabItem label="TypeScript">
        Run `aspire restore` after referencing the hosting integration in `aspire.config.json`, as shown in the hosting integration article. ATS generates the `addMailDev` method and its typed options.

        ```typescript title="apphost.mts"
        import { createBuilder } from './.aspire/modules/aspire.mjs';

src/frontend/src/content/docs/integrations/custom-integrations/hosting-integrations.mdx:344

• The TypeScript tab’s fenced JSON/TypeScript blocks are heavily indented, which can prevent Markdown from recognizing them as fenced code blocks and is inconsistent with other Tabs examples. De-indent the tab content so the fences start near the left margin.

    <TabItem label="TypeScript">
        Reference the local integration project from `aspire.config.json`. The key is the integration assembly name, and the project path is relative to the configuration file.

        ```json title="aspire.config.json"
        {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

🤖 Automated docs-accuracy review — PR #1498

Phase A source of truth: microsoft/aspire @ release/13.5 (SHA 8ab6999850d96e0023670799edbd4bdc245ad63c)
Claims evaluated: 10 core source-of-truth claims → 8 verified, 2 verified-with-nuance, 0 unverifiable, 0 contradicted.
Phase B (rendered docs, served from the PR head in a real browser): 3 changed pages exercised → 0 critical, 2 warnings. No console errors; Tabs, code blocks, images, and internal links all render.

Verdict: 💬 COMMENT — everything the PR asserts about ATS checks out against release/13.5 source and renders correctly. The two warnings are a merge-ordering dependency and a small onboarding gap; neither blocks.

---

Phase A — Claim verification

No contradicted or unverifiable claims. The [AspireExport] / [ResourceName] attributes, the ATS → TypeScript generation pipeline, aspire restore codegen, the .aspire/modules layout, the aspire.config.json packages mapping, addCSharpApp, AddParameter(secret:), and the AddMailDev → addMailDev(name, { …options }) naming convention are all present in release/13.5.

All 10 claim verdicts with source evidence

#	Claim	Verdict	Evidence (microsoft/aspire@release/13.5)
C1	[AspireExport] applies to resource classes and extension methods	verified	src/Aspire.Hosting/Ats/AspireExportAttribute.cs:4,83-87 — namespace Aspire.Hosting; AttributeUsage allows Method, Class, Interface, Assembly, Property
C2	[ResourceName] applies to a string name parameter	verified	src/Aspire.Hosting/ApplicationModel/ResourceNameAttribute.cs:4,18-19 — namespace Aspire.Hosting.ApplicationModel; targets Parameter
C3	ATS uses [AspireExport] metadata to generate a typed TS API that calls the C# impl	verified	Aspire.Hosting.RemoteHost/AtsContextFactory.cs:58-81, AtsCapabilityScanner.cs:410-444, CodeGeneration/CodeGenerationService.cs:240-252, Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs:835-844; analyzer diagnostics at Aspire.Hosting.Integration.Analyzers/AspireExportAnalyzer.Diagnostics.cs:13-27
C4	aspire restore generates the typed API	verified	src/Aspire.Cli/Commands/RestoreCommand.cs:17-21,47,150-158; Projects/GuestAppHostProject.cs:1071-1083 (aspire run also triggers generation)
C5	Generated modules live under .aspire/modules, imported via ./.aspire/modules/aspire.mjs	verified‑with‑nuance	Projects/GuestAppHostProject.cs:1593-1623; AtsTypeScriptCodeGenerator.cs:839-844. Nuance: the generator emits source named aspire.mts/base.mts/transport.mts; .mjs is the import specifier — so the PR's import … from './.aspire/modules/aspire.mjs' is correct
C6	aspire.config.json packages maps an assembly name → a version or a .csproj path (relative to the config file)	verified‑with‑nuance	Configuration/AspireConfigFile.cs:121-123,337-344,374-379; Configuration/IntegrationReference.cs:13-25,51-60; Projects/PrebuiltAppHostServer.cs:169-188. Nuance: source calls the key "package or assembly name" and, for project refs, does not strictly validate that the key equals the assembly name — so "the key is the integration assembly name" is accurate in practice but not enforced
C7	addCSharpApp(name, path, options?) accepts a project directory path	verified	src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs:330-337,364-369,381-388; TS snapshot tests/…/TwoPassScanningGeneratedAspire.verified.ts:10881-10885. Path may be .cs, .csproj, or a directory, so ./NewsletterService is valid
C8	C# AddParameter(name, secret: true)	verified	src/Aspire.Hosting/ParameterResourceBuilderExtensions.cs:27-29 — bool secret = false overload
C9	AddMailDev → addMailDev('maildev', { username, password }) (camelCase; builder arg dropped; optionals bundled into a trailing options object)	verified	AtsCapabilityScanner.cs:1983-2008,2038-2065,2095-2164,3321-3331; AtsTypeScriptCodeGenerator.cs:1406-1428,1600-1622,1634-1650,2197-2215
C10	Aspire.Hosting / template 13.5.0	verified	eng/Versions.props:3-8 — 13.5.0

Third‑party pins (MailKit 4.17.0, OpenTelemetry.Extensions.Hosting 1.17.0) are outside the Aspire source of truth; they render correctly and are consistent with the net10.0 target. The narrative ATS prose ("ATS generates TypeScript APIs for the hosting integration; the MailKit client stays standard .NET and needs no ATS annotations") is accurate — client integrations are consumed inside the C# service, not from the TS AppHost.

---

Phase B — doc-tester results (rendered site, blind to source)

Served the PR head locally and browsed the three changed pages in a real browser.

Pages exercised

• /integrations/custom-integrations/hosting-integrations/
• /integrations/custom-integrations/client-integrations/
• /integrations/custom-integrations/secure-communication/
• (link target) /extensibility/multi-language-integration-authoring/

✅ Passed checks

• All three pages compile and render — no MDX errors; correct page titles.
• Zero browser console errors or warnings on every page.
• New [AspireExport] intro paragraph renders (hosting-integrations) with a working link to Multi-language integrations.
• <Tabs syncKey='aspire-lang'> C#/TypeScript tabs render on hosting-integrations and secure-communication, switch correctly, and the selection syncs across pages and updates the URL (?aspire-lang=…).
• TypeScript samples render exactly as written: aspire.config.json packages mapping; apphost.mts with createBuilder, addMailDev('maildev'), addParameter('maildev-password', { secret: true }), addMailDev('maildev', { username, password }), addCSharpApp('newsletterservice', './NewsletterService').withReference(maildev), build().run().
• C# samples render correctly: AddParameter("maildev-password", secret: true), AddMailDev(name:, username:, password:), AddProject<…>().WithReference(maildev).
• client-integrations: ATS note + MailKit 4.17.0 / OpenTelemetry.Extensions.Hosting 1.17.0 render.
• Internal cross-reference /extensibility/multi-language-integration-authoring/ resolves (HTTP 200).

⚠️ Warnings / recommendations (non-blocking)

• W1 — Sample link is dead until aspire-samples#1891 lands. All three pages link to https://github.com/microsoft/aspire-samples/tree/main/samples/maildev-mailkit, but that path returns 404 on main today and the referenced sample PR (microsoft/aspire-samples#1891, "Add MailDev and MailKit custom integration sample") is still open/unmerged. A reader who clicks "MailDev and MailKit custom integrations sample" currently hits a 404. Recommend coordinating merge order (land #1891 first, or hold this PR until it merges). (Flagging as a content/merge-ordering dependency, not a lint — this cross-repo link isn't covered by the internal links validator.)
• W2 — TypeScript onboarding gap. The TypeScript tabs jump straight to "Reference the local integration project from aspire.config.json" and "run aspire restore," but the tutorial's Set up the starter project section only shows creating a C# AppHost (dotnet new aspire). A reader following the TS path isn't told how to create a TypeScript AppHost or where aspire.config.json comes from. It's mitigated by the link to Multi-language integrations and the sample, but a one-line pointer at the first TypeScript tab would smooth the path.

Knowledge gap: W2 — on-page setup for the TypeScript AppHost is assumed rather than shown.

---

_{Phase A verified claims against microsoft/aspire@release/13.5 source; Phase B validated the rendered PR head in a browser and stayed blind to product source. No contradictions and no critical rendering issues found.}

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1498. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.