Repository navigation
[docs] Document Azure API Management hosting integration - #2083
Open
Eric Erhardt (eerhardt) wants to merge 1 commit into
Open
Eric Erhardt (eerhardt) wants to merge 1 commit into
Eric Erhardt (eerhardt) wants to merge 1 commit into
Conversation
Add a set of pages that document the Aspire.Hosting.Azure.ApiManagement hosting integration (microsoft/aspire#19664): get started, APIs and operations, OpenAPI import, backends and pools, policies and named values, products and subscriptions, service configuration, and networking. Add the sidebar group and an APIM note to the Azure Virtual Network private endpoint guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Eric Erhardt (eerhardt)
requested a review
from David Pine (IEvangelist)
as a code owner
November 7, 2026 00:00
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved documentation issues include incomplete package installation instructions, an uncreated Key Vault secret in both examples, and inaccurate subnet restrictions and missing-file exception guidance.
5 open issues
What changed in this PR
Adds eight focused guides for the Azure API Management hosting integration in Aspire 17.0, covering setup through deployment and advanced configuration.
Changes:
- Documents APIs, OpenAPI imports, backends, policies, products, and service configuration with TypeScript and C# examples.
- Explains networking models, tier restrictions, and private-endpoint public-access behavior.
- Adds sidebar navigation and links from the existing Azure Virtual Network guide.
| File | Description |
|---|---|
| src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx | Adds APIM-specific private-endpoint guidance. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-service.mdx | Covers identity, diagnostics, domains, and existing services. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-products.mdx | Documents products, subscriptions, and key retrieval. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-policies.mdx | Explains policies, fragments, and named values. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-openapi.mdx | Covers file and deployed-endpoint imports. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-networking.mdx | Documents network integration, injection, and private endpoints. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-get-started.mdx | Introduces installation, deployment, pricing tiers, and limitations. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-backends.mdx | Covers backends, authentication, circuit breakers, and pools. |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-api-management/azure-api-management-apis.mdx | Documents workload routing and API operations. |
| src/frontend/config/sidebar/integrations.topics.ts | Adds the Azure API Management navigation group. |
Review effort: Balanced
|
|
||
| To access these types and APIs, add the [📦 Aspire.Hosting.Azure.ApiManagement](https://www.nuget.org/packages/Aspire.Hosting.Azure.ApiManagement) NuGet package to your AppHost project. | ||
|
|
||
| <InstallPackage packageName="Aspire.Hosting.Azure.ApiManagement" /> |
|
|
||
| ### Add a service and route a workload | ||
|
|
||
| Call `AddAzureApiManagement` to add the service, then call `AddApi` with a compute resource to publish that workload through the gateway: |
|
|
||
| The following rules apply to every model: | ||
|
|
||
| - Each APIM service needs a dedicated subnet. A subnet that one APIM service uses can't be used by another. |
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| Aspire reads the file when it generates infrastructure for publish or deploy, not during `aspire run`. The file doesn't need to exist for local development. When you publish or deploy, the file must exist and contain non-whitespace content, or Aspire throws an `InvalidOperationException`. |
Comment on lines
+206
to
+207
| const vault = await builder.addAzureKeyVault("vault"); | ||
| await apim.addKeyVaultNamedValue("shared-secret", vault, "shared-secret", { |
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the Azure API Management (APIM) hosting integration (
Aspire.Hosting.Azure.ApiManagement) added in microsoft/aspire#19664 for Aspire 17.0. This PR supersedes #2041 and consolidates the APIM docs into one folder of eight focused pages underintegrations/cloud/azure/azure-api-management/:aspire run, provisioned byaspire deploy), SKU/capacity table with validation, deployment outputs,ConfigureInfrastructure(C#-only), security considerations, current limitations.AddApi, standalone APIs andWithBackend, generated wildcard proxy operations, explicit operations, OpenAI-compatible APIs.WithOpenApiDocument(file) andWithOpenApiEndpoint(deployed workload endpoint), format handling, one-source rule.PublishAsExisting.Other changes:
What I took from #2041: the overall single-service framing and the quick-start idea. What I changed: the sidebar position (it was inserted before Application Insights), the identity model (main uses a user-assigned identity; the PR description's system-assigned identity is outdated), the experimental diagnostic (see assumptions), and every sample was rebuilt so it compiles.
Assumptions and notes
[Experimental]; the package ships as a prerelease. The virtual network APIs that APIM networking uses (AddAzureVirtualNetwork,AddPrivateEndpoint,WithInternalLoadBalancer) reportASPIREAZURE003, and the pages call that out where it applies.aspire-langtabs with TypeScript first. C#-only APIs (ConfigureInfrastructure, output references, theIdentityproperty) have a note beside them. The TypeScript snippets use plaintypescriptfences (nottwoslash) because the repo's generated TypeScript API data (13.6.0) doesn't include APIM.AddProject<T>: it's marked obsolete in the 17.0 preview (useAddDotnetProject), but I keptAddProject<Projects.X>/addProject(...)in samples to match the other 700+ samples in the repo. Easy to flip if the 17.0 docs standardize on the new API.Aspire.Hosting.Azure.ApiManagementreturns 404 on nuget.org, so the NuGet link on the Get started page won't resolve until the package ships. For the same reason I did not add anintegration-docs.jsonmapping:aspire-integrations.jsonis generated from NuGet, andreconcileIntegrationDocs(covered bytest:unit:structured-data) drops official-package mappings that aren't in the catalog. AddAspire.Hosting.Azure.ApiManagement->/integrations/cloud/azure/azure-api-management/azure-api-management-get-started/once the package is published and in the catalog.gatewayUrlhost form, and circuit-breaker failover behavior beyond what the generated Bicep shows.Third-party links and affiliations
None. New links go to
learn.microsoft.com,nuget.org(Microsoft's own package), and aspire.dev pages.Validation
Source verification (local harnesses outside the repo):
main(the package has only the PR's merge commit, somainmatches the PR).Aspire.Hosting.Azure.ApiManagement17.0.0-preview.1.26554.22(and AppContainers) with the Aspire CLI and compiled all 31 TypeScript snippets withnpx tsc --noEmit: 0 errors.dotnet build: 0 errors, 0 warnings (CS0618for obsoleteAddProject<T>andASPIRE012for the obsolete AppHost SDK are suppressed deliberately).aspire publishon a sample AppHost to confirm the generated Bicep (service name, backend names,proxy-{method}operations, outputs) and the run-mode vs publish-mode resource model.Repo checks (run from
src/frontend):pnpm test:unit:structured-data: passed (5 files, 99 tests)pnpm test:unit:twoslash-blocks: passed (2 tests)pnpm test:unit:docs: passed (2 tests)pnpm exec astro sync: passed (content collection frontmatter schema)pnpm exec eslint config/sidebar/integrations.topics.ts --max-warnings 0: passedpnpm check-data: passedpnpm buildwas intentionally not run locally (CI runs it).