[Docs][13.3] AppHost: missing conceptual documentation for 25 new APIs/behaviors

[joperezr]

Aspire 13.3 — AppHost conceptual docs gap

This issue tracks 25 AppHost changes shipped in Aspire 13.3 that introduce new APIs, behaviors, or user-visible surfaces with no conceptual documentation in microsoft/aspire.dev. This issue is scoped to the missing conceptual docs only — the What's New release-notes entries are being handled separately.

Source: 13.3 Change log wiki. Audit performed against release/13.3.

The Owner column is the author of the source PR (or first-write-access author if multiple); contributor-only rows are unowned and need to be picked up by the team. Use the Progress checklist below the table to mark items done — GitHub doesn't render checkable checkboxes inside table cells, so the checklist is separate.

Items needing docs

#	Title	Type	Source PR(s)	Suggested doc location	Owner
1	BeforeStart pipeline steps for ordered startup across all compute environments	feature	#13780, #16414	deployment/pipelines.mdx (extend)	@eerhardt
2	Predefined value catalogs for polyglot AppHosts ([AspireValue])	feature	#16287	extensibility/multi-language-integration-authoring.mdx (extend)	@sebastienros
3	Privileged mode support for Docker Compose publishing	feature	#16075	deployment/docker-compose.mdx (extend)
4	Customize AKS system node pool VM size	feature	#16312	integrations/cloud/azure/aks/index.mdx (extend)	@mitchdenny
5	Private endpoint support for Azure Container Registry	feature	#16132	deployment/azure/	@eerhardt
6	Dockerfile builder APIs for polyglot AppHosts	feature	#15867	app-host/withdockerfile.mdx + extensibility/multi-language-integration-authoring.mdx	@sebastienros
7	HTTP command result support for AppHost commands	feature	#15664	reference/api or fundamentals/http-commands.mdx	@davidfowl
8	Resource commands can return structured results	feature	#15622, #15906	fundamentals/custom-resource-commands.mdx (extend)	@davidfowl, @JamesNK
9	Unified withEnvironment API for polyglot AppHosts	feature	#15649	extensibility/multi-language-integration-authoring.mdx	@sebastienros
10	Extension methods for subscribing to app host lifecycle events	feature	#14119	app-host/eventing.mdx
11	Exclude management endpoints from default WithReference() (IsDefaultReferenceEndpoint)	feature	#15558	fundamentals/networking/service-discovery.mdx (extend)	@danegsta
12	API review breaking changes (AKS SKU tier, EF Core ContextTypeName, JS diagnostic ID)	improvement	#16674	various integration pages
13	Endpoint property expressions available in polyglot AppHost SDKs	improvement	#16540	extensibility/multi-language-integration-authoring.mdx	@sebastienros
14	Explicit compute environment binding enforced for multi-environment deployments	improvement	#16499, #16411	deployment/overview.mdx	@eerhardt
15	Build-time detection of duplicate polyglot capability IDs (ASPIREEXPORT013)	improvement	#16530	diagnostics/aspireexport013.mdx (new)	@sebastienros
16	Docker Compose API parity for polyglot AppHosts	improvement	#16364	deployment/docker-compose.mdx + extensibility/multi-language-integration-authoring.mdx	@sebastienros
17	Configurable Azure credential process timeout	improvement	#16175	deployment/azure/
18	ASPIRE_ENVIRONMENT variable support in AppHost	improvement	#16098	app-host/configuration.mdx (new section)	@davidfowl
19	Automatic HTTPS upgrade for Azure App Service endpoints	improvement	#16060	deployment/azure/azure-app-service.mdx (extend)	@davidfowl
20	Configurable name validation with NameValidationPolicyAnnotation	improvement	#15728	extensibility/multi-language-integration-authoring.mdx	@JamesNK
21	Custom domain configuration in polyglot AppHosts for Azure Container Apps	improvement	#15811	deployment/azure/aca/ + extensibility/multi-language-integration-authoring.mdx	@sebastienros
22	Unified YARP TypeScript route helpers (addRoute/addCatchAllRoute)	improvement	#15729	extensibility/multi-language-integration-authoring.mdx	@sebastienros
23	Logger property added to ExecuteCommandContext	improvement	#15678	fundamentals/custom-resource-commands.mdx
24	Use ASP.NET Core dev cert for DCP to improve certificate trust	improvement	#15718	app-host/configuration.mdx	@danegsta
25	Export WithAdminDeploymentScriptSubnet for TypeScript polyglot app hosts	improvement	#15564	extensibility/multi-language-integration-authoring.mdx	@mitchdenny

Progress checklist

• 1. BeforeStart pipeline steps for ordered startup across all compute environments (does not require conceptual docs) — @eerhardt
• 2. Predefined value catalogs for polyglot AppHosts ([AspireValue]) — @sebastienros
• 3. Privileged mode support for Docker Compose publishing
• 4. Customize AKS system node pool VM size — @mitchdenny
• 5. Private endpoint support for Azure Container Registry [docs] Add private endpoint support for Azure Container Registry #770 — @eerhardt
• 6. Dockerfile builder APIs for polyglot AppHosts — @sebastienros
• 7. HTTP command result support for AppHost commands — @davidfowl
• 8. Resource commands can return structured results — @davidfowl, @JamesNK
• 9. Unified withEnvironment API for polyglot AppHosts — @sebastienros
• 10. Extension methods for subscribing to app host lifecycle events [docs] AppHost eventing: document OnBeforeStart, OnBeforePublish, OnAfterPublish builder extension methods #821
• 11. Exclude management endpoints from default WithReference() (IsDefaultReferenceEndpoint) — @danegsta
• 12. API review breaking changes (AKS SKU tier, EF Core ContextTypeName, JS diagnostic ID)
• 13. Endpoint property expressions available in polyglot AppHost SDKs — @sebastienros
• 14. Explicit compute environment binding enforced for multi-environment deployments (does not require conceptual docs) — @eerhardt
• 15. Build-time detection of duplicate polyglot capability IDs (ASPIREEXPORT013) — @sebastienros
• 16. Docker Compose API parity for polyglot AppHosts — @sebastienros
• 17. Configurable Azure credential process timeout
• 18. ASPIRE_ENVIRONMENT variable support in AppHost — @davidfowl
• 19. Automatic HTTPS upgrade for Azure App Service endpoints — @davidfowl
• 20. Configurable name validation with NameValidationPolicyAnnotation — @JamesNK
• 21. Custom domain configuration in polyglot AppHosts for Azure Container Apps — @sebastienros
• 22. Unified YARP TypeScript route helpers (addRoute/addCatchAllRoute) — @sebastienros
• 23. Logger property added to ExecuteCommandContext [docs] Add Logger property to ExecuteCommandContext docs #818
• 24. Use ASP.NET Core dev cert for DCP to improve certificate trust — @danegsta
• 25. Export WithAdminDeploymentScriptSubnet for TypeScript polyglot app hosts — @mitchdenny

Per-item rationale and content guidance

1. BeforeStart pipeline steps for ordered startup across all compute environments

• Type: feature
• Source PR(s): #13780, #16414
• Where to add docs: deployment/pipelines.mdx (extend)
• Why it needs docs / what to cover: BeforeStart pipeline steps (replacing eventing-subscriber classes for Kubernetes/Docker Compose/AKS) are a major architectural shift — needs explicit migration guidance.

2. Predefined value catalogs for polyglot AppHosts ([AspireValue])

• Type: feature
• Source PR(s): #16287
• Where to add docs: extensibility/multi-language-integration-authoring.mdx (extend)
• Why it needs docs / what to cover: [AspireValue] attribute and predefined value catalogs (e.g. FoundryModels.OpenAI.Gpt41Mini) are not documented anywhere; only AspireValue is referenced once in extensibility doc but no concept guide.

3. Privileged mode support for Docker Compose publishing

• Type: feature
• Source PR(s): #16075
• Where to add docs: deployment/docker-compose.mdx (extend)
• Why it needs docs / what to cover: Privileged mode (PublishAsDockerComposeService with privileged) is not documented despite docker-compose.mdx covering many other options.

4. Customize AKS system node pool VM size

• Type: feature
• Source PR(s): #16312
• Where to add docs: integrations/cloud/azure/aks/index.mdx (extend)
• Why it needs docs / what to cover: AddSystemNodePool extension method not documented in AKS integration page.

5. Private endpoint support for Azure Container Registry

• Type: feature
• Source PR(s): #16132
• Where to add docs: deployment/azure/
• Why it needs docs / what to cover: WithPrivateEndpoint on ACR is documented in azure-virtual-network.mdx for general usage, but no specific mention for Azure Container Registry. Could be a new section.

6. Dockerfile builder APIs for polyglot AppHosts

• Type: feature
• Source PR(s): #15867
• Where to add docs: app-host/withdockerfile.mdx + extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: withdockerfile.mdx exists for C# but the polyglot DockerfileBuilder API is not documented. Diagnostics/aspiredockerfilebuilder001.mdx exists but is just a diagnostic. Need polyglot section + What's New entry.

7. HTTP command result support for AppHost commands

• Type: feature
• Source PR(s): #15664
• Where to add docs: reference/api or fundamentals/http-commands.mdx
• Why it needs docs / what to cover: HttpCommandResultMode and HttpCommandOptions.ResultMode not documented. fundamentals/http-commands.mdx should cover the new return-body flow.

8. Resource commands can return structured results

• Type: feature
• Source PR(s): #15622, #15906
• Where to add docs: fundamentals/custom-resource-commands.mdx (extend)
• Why it needs docs / what to cover: custom-resource-commands.mdx mentions ExecuteCommandResult (5x) but does not document the new Message property, structured results pipeline, or the dashboard notification center wiring.

9. Unified withEnvironment API for polyglot AppHosts

• Type: feature
• Source PR(s): #15649
• Where to add docs: extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: Unified withEnvironment polyglot API not documented.

10. Extension methods for subscribing to app host lifecycle events

• Type: feature
• Source PR(s): #14119
• Where to add docs: app-host/eventing.mdx
• Why it needs docs / what to cover: eventing.mdx covers BeforeStartEvent etc, but does not document the new IDistributedApplicationBuilder Subscribe extension methods (e.g. SubscribeBeforeStart) added in #14119. Should also call out community contribution.

11. Exclude management endpoints from default WithReference() (IsDefaultReferenceEndpoint)

• Type: feature
• Source PR(s): #15558
• Where to add docs: fundamentals/networking/service-discovery.mdx (extend)
• Why it needs docs / what to cover: IsDefaultReferenceEndpoint on EndpointAnnotation and the new behavior (management endpoints excluded from WithReference) are not documented anywhere.

12. API review breaking changes (AKS SKU tier, EF Core ContextTypeName, JS diagnostic ID)

• Type: improvement
• Source PR(s): #16674
• Where to add docs: various integration pages
• Why it needs docs / what to cover: Bundle of API review breaking changes (AKS SKU tier rename to WithFreeAksSkuTier/WithStandardAksSkuTier, EF Core ContextTypeName→DbContextTypeName, JS diagnostic ID renamed to ASPIREJAVASCRIPT001). Breaking — must be in 13-3 What's New.

13. Endpoint property expressions available in polyglot AppHost SDKs

• Type: improvement
• Source PR(s): #16540
• Where to add docs: extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: Endpoint property expressions in polyglot SDKs — extend polyglot extensibility docs.

14. Explicit compute environment binding enforced for multi-environment deployments

• Type: improvement
• Source PR(s): #16499, #16411
• Where to add docs: deployment/overview.mdx
• Why it needs docs / what to cover: Explicit compute-environment binding now enforced for multi-environment deployments — behavior change worth documenting.

15. Build-time detection of duplicate polyglot capability IDs (ASPIREEXPORT013)

• Type: improvement
• Source PR(s): #16530
• Where to add docs: diagnostics/aspireexport013.mdx (new)
• Why it needs docs / what to cover: New build-time diagnostic ASPIREEXPORT013 — needs diagnostic page.

16. Docker Compose API parity for polyglot AppHosts

• Type: improvement
• Source PR(s): #16364
• Where to add docs: deployment/docker-compose.mdx + extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: Docker Compose API parity for polyglot — extend polyglot docs.

17. Configurable Azure credential process timeout

• Type: improvement
• Source PR(s): #16175
• Where to add docs: deployment/azure/
• Why it needs docs / what to cover: New Azure__CredentialProcessTimeoutSeconds config — needs configuration docs.

18. ASPIRE_ENVIRONMENT variable support in AppHost

• Type: improvement
• Source PR(s): #16098
• Where to add docs: app-host/configuration.mdx (new section)
• Why it needs docs / what to cover: New ASPIRE_ENVIRONMENT variable for AppHost environment — needs config docs.

19. Automatic HTTPS upgrade for Azure App Service endpoints

• Type: improvement
• Source PR(s): #16060
• Where to add docs: deployment/azure/azure-app-service.mdx (extend)
• Why it needs docs / what to cover: New WithHttpsUpgrade behavior for App Service — needs documentation in App Service deployment docs.

20. Configurable name validation with NameValidationPolicyAnnotation

• Type: improvement
• Source PR(s): #15728
• Where to add docs: extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: New NameValidationPolicyAnnotation for configurable name validation — needs API/extensibility docs.

21. Custom domain configuration in polyglot AppHosts for Azure Container Apps

• Type: improvement
• Source PR(s): #15811
• Where to add docs: deployment/azure/aca/ + extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: Custom domain configuration for ACA in polyglot AppHosts — needs ACA + polyglot docs.

22. Unified YARP TypeScript route helpers (addRoute/addCatchAllRoute)

• Type: improvement
• Source PR(s): #15729
• Where to add docs: extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: Unified TS YARP route helpers (addRoute/addCatchAllRoute) — needs polyglot YARP docs.

23. Logger property added to ExecuteCommandContext

• Type: improvement
• Source PR(s): #15678
• Where to add docs: fundamentals/custom-resource-commands.mdx
• Why it needs docs / what to cover: New Logger property on ExecuteCommandContext — should be in custom resource commands docs.

24. Use ASP.NET Core dev cert for DCP to improve certificate trust

• Type: improvement
• Source PR(s): #15718
• Where to add docs: app-host/configuration.mdx
• Why it needs docs / what to cover: New ASPIRE_DCP_DEVELOPER_CERTIFICATE behavior using ASP.NET Core dev cert. Configurable behavior — needs documentation.

25. Export WithAdminDeploymentScriptSubnet for TypeScript polyglot app hosts

• Type: improvement
• Source PR(s): #15564
• Where to add docs: extensibility/multi-language-integration-authoring.mdx
• Why it needs docs / what to cover: WithAdminDeploymentScriptSubnet exported for polyglot — needs polyglot SQL/networking docs.

---

This issue was generated from a structured audit of the 13.3 changelog against the release/13.3 branch of aspire.dev.

[JamesNK]

Configurable name validation with NameValidationPolicyAnnotation

I don't think docs are needed. Primarily for internal use.

[JamesNK]

Resource commands can return structured results

Already done.