Adds a new section that describes WithReference and equivalent methods in the "What are Aspire Integrations?" article#795
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation section to the “What are Aspire integrations?” overview page explaining how WithReference() (and language equivalents) wire AppHost resources to consuming projects via injected environment variables, helping reduce repetition across individual integration connection articles.
Changes:
- Introduces a new “Wiring resources to consuming projects with references” section describing
WithReference()semantics. - Adds AppHost-language pivoted examples (C# / TypeScript) and a follow-up section showing how injected environment variables can be consumed.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <PivotSelector | ||
| title="Select your AppHost language" | ||
| key="aspire-lang" | ||
| options={[ | ||
| { id: 'csharp', title: 'C#' }, | ||
| { id: 'typescript', title: 'TypeScript' }, | ||
| ]} | ||
| /> |
There was a problem hiding this comment.
Use tabs here, no need for the pivot. You're already using tabs below.
|
|
||
| ## Wiring resources to consuming projects with references | ||
|
|
||
| Once you've created resources, such as databases or messaging systems, by setting up hosting integrations in the AppHost, you can pass those resources to consuming projects, such as APIs or web apps, by calling the `WithReference` method, or its equivalent for your preferred language. These methods express an explicit dependency between a resource and a consuming project. When Aspire starts, it injects connection information as environment variables into the consuming project so it can locate and connect to that resource. |
There was a problem hiding this comment.
| Once you've created resources, such as databases or messaging systems, by setting up hosting integrations in the AppHost, you can pass those resources to consuming projects, such as APIs or web apps, by calling the `WithReference` method, or its equivalent for your preferred language. These methods express an explicit dependency between a resource and a consuming project. When Aspire starts, it injects connection information as environment variables into the consuming project so it can locate and connect to that resource. | |
| Once you've created resources, such as databases or messaging systems, by setting up hosting integrations in the AppHost, you can pass those resources to consuming projects, such as APIs or web apps, by calling the "with reference" APIs. These methods express an explicit dependency between a resource and a consuming project. When Aspire starts, it injects connection information as environment variables into the consuming project so it can locate and connect to that resource. |
| The environment variables Aspire injects depend on the type of resource being referenced. For example: | ||
|
|
||
| - **Connection string resources**: Aspire sets a `ConnectionStrings__{name}` environment variable, where `{name}` matches the resource name. For example, `.WithReference(cache)` on a resource named `"cache"`, that is available on port 6379, injects `ConnectionStrings__cache=localhost:6379`. | ||
| - **Service endpoint resources**: Aspire sets `services__{name}__{scheme}__{index}` variables used for service discovery. For example, referencing a project named `api`, that is available on port 7001, injects `services__api__https__0=https://localhost:7001`. |
There was a problem hiding this comment.
Use the simple env var names instead of the legacy names.
|
|
||
| The environment variables Aspire injects depend on the type of resource being referenced. For example: | ||
|
|
||
| - **Connection string resources**: Aspire sets a `ConnectionStrings__{name}` environment variable, where `{name}` matches the resource name. For example, `.WithReference(cache)` on a resource named `"cache"`, that is available on port 6379, injects `ConnectionStrings__cache=localhost:6379`. |
There was a problem hiding this comment.
Try to avoid a callout to an explicit .NET API, simply say something like "when one resource chains a call to reference another resource". Leave the code parts for the tabs.
|
|
||
| Any application can read these environment variables to connect to its dependencies. A Python, Node.js, or other app can read variables directly, without any Aspire-specific libraries. | ||
|
|
||
| If your consuming project is written in .NET C#, you have an additional option: [**Aspire client integrations**](#client-integrations): |
There was a problem hiding this comment.
Try to avoid saying ".NET", "C#" is much better branding. Also, I think we should just let the tabs speak for themselves. Instead of calling out C# here - instead let the reader select C# if they want those details. In other words, please just fold this into the C# tab, let the reader know they can manually use Environment.GetEnvironmentVariable or the IConfiguration APIs, or preferably use the official client integrations.
| If your consuming project is written in .NET C#, you have an additional option: [**Aspire client integrations**](#client-integrations): | |
| If your consuming project is written in C#, you have an additional option: [**Aspire client integrations**](#client-integrations): |
|
|
||
| Once you've created resources, such as databases or messaging systems, by setting up hosting integrations in the AppHost, you can pass those resources to consuming projects, such as APIs or web apps, by calling the `WithReference` method, or its equivalent for your preferred language. These methods express an explicit dependency between a resource and a consuming project. When Aspire starts, it injects connection information as environment variables into the consuming project so it can locate and connect to that resource. | ||
|
|
||
| <PivotSelector |
There was a problem hiding this comment.
Maybe we should have a generic mermaid diagram here or nearby, the is similar to what was added in the Postgres get started, that shows two "resources" modeled in the AppHost and helps visualize how hosting and client integrations relate from that perspective.
This PR adds a discussion of
WithReference()and equivalent methods for other AppHost languages, to the What are Aspire integrations? article. This approach will reduce the amount of language-specific examples we have to include in the connection article for each integration.Fixes: #794