You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When writing documentation or editing .md files, follow the following guidelines:
2
+
3
+
Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
4
+
5
+
Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
6
+
7
+
Headings should be in sentence case, not title case. Don't use gerunds in titles.
8
+
9
+
Use the active voice whenever possible, and second person to address the reader directly.
10
+
11
+
Use a conversational tone with contractions.
12
+
13
+
Be concise.
14
+
15
+
Break up long sentences.
16
+
17
+
Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
18
+
19
+
Do not use "we" or "our" to refer to the authors of the documentation.
20
+
21
+
Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method."
22
+
23
+
Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception."
24
+
25
+
Use the Oxford comma in lists of three or more items.
26
+
27
+
Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists.
28
+
29
+
Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized.
30
+
31
+
Put raw URLs within angle brackets.
32
+
33
+
Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link.
34
+
35
+
When mentioning APIs, use cross-references to the API documentation. These links are formatted as <xref:api-doc-ID>. You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `<TypeSignature>` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `<MemberSignature>` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is <xref:System.String>.
36
+
37
+
If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo.
38
+
39
+
If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project.
40
+
41
+
If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name.
When you're assigned an issue that's labeled "breaking-change", or when you're given a link to an issue that's labeled "breaking-change" and asked to create a new breaking change document, follow the following guidelines:
2
+
3
+
The document should be in Markdown format.
4
+
5
+
.NET Aspire breaking changes live in the https://github.com/dotnet/docs-aspire/tree/main/docs/compatibility folder and its subfolders.
6
+
7
+
Rephrase all content to be clear and concise, if necessary.
8
+
9
+
Describe previous behavior in past tense and new behavior in present tense.
10
+
11
+
The document should start with the following frontmatter, including `---` characters. Placeholder text is shown in angle brackets.
description: "Learn about the breaking change in <product/version without the preview number> where <verybriefdescription>."
16
+
ms.date: <Today's date>
17
+
ai-usage: ai-assisted
18
+
ms.custom: <URLoftheGitHubissue>
19
+
---
20
+
21
+
After the frontmatter, include the following sections in this order. Use the description in parentheses as a guide for the content of each section.
22
+
23
+
h1: "(The same title used in the document header, sans 'Breaking Change - ')"
24
+
25
+
(An introductory paragraph summarizing the breaking change. Include the major version but not the preview number.)
26
+
27
+
h2: Version introduced
28
+
29
+
(The version in which the breaking change was introduced. Include the preview number here, if given.)
30
+
31
+
h2: Previous behavior
32
+
33
+
(A brief description of the behavior before the change, including an example code snippet if applicable.)
34
+
35
+
h2: New behavior
36
+
37
+
(A brief description of the behavior after the change, including an example code snippet if applicable.)
38
+
39
+
h2: Type of breaking change
40
+
41
+
If the type of breaking change is "behavioral change", add the following sentence (without the backticks): `This is a [behavioral change](../../categories.md#behavioral-change).`
42
+
43
+
If the type of breaking change is "source incompatible" or "binary incompatible", add the following sentence (without the backticks): `This change can affect [source compatibility](../../categories.md#source-compatibility).` or `This change can affect [binary compatibility](../../categories.md#binary-compatibility).`
44
+
45
+
If the issue lists multiple types of breaking changes, create a single sentence that links to each applicable type, such as "This is both a []() and []() change.". If there is no type of breaking change selected in the issue, write "TODO: Add type of breaking change."
46
+
47
+
h2: Reason for change
48
+
49
+
(The complete reasoning behind the change, including any relevant links.)
50
+
51
+
h2: Recommended action
52
+
53
+
(A brief description of the action or actions that users should take, including example code snippets if applicable.)
54
+
55
+
h2: Affected APIs
56
+
57
+
(A bullet list of APIs that are affected by the change. If there are no affected APIs (or "No response") write "None.". Use xref-style links as described in the copilot-instructions.md file. At the end of each doc ID, add "?displayProperty=fullName", for example "<xref:System.String?displayProperty=fullName>".)
58
+
59
+
Then, add the new document to both the "By area" and "By version" sections of the TOC file located at https://github.com/dotnet/docs-aspire/tree/main/docs/compatibility/toc.yml. Also add an entry to the index file under the appropriate area H2 heading in the https://github.com/dotnet/docs-aspire/tree/main/docs/compatibility/9.3/index.md file by adding a row to the table (create a new heading/table if it doesn't exist yet).
60
+
61
+
Next, create a pull request. In the description, include the text "Fixes #\<issue-number>", where "issue-number" is the GitHub issue number.
Copy file name to clipboardExpand all lines: docs/fundamentals/setup-tooling.md
+13-6Lines changed: 13 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: .NET Aspire tooling
3
3
description: Learn about essential tooling concepts for .NET Aspire.
4
-
ms.date: 04/15/2025
4
+
ms.date: 05/30/2025
5
5
zone_pivot_groups: dev-environment
6
6
uid: dotnet/aspire/setup-tooling
7
7
---
@@ -23,7 +23,9 @@ To work with .NET Aspire, you need the following installed locally:
23
23
24
24
-[.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9.0](https://dotnet.microsoft.com/download/dotnet/9.0).
25
25
- An OCI compliant container runtime, such as:
26
-
-[Docker Desktop](https://www.docker.com/products/docker-desktop) or [Podman](https://podman.io/). For more information, see [Container runtime](#container-runtime).
-_For more information, see [Container runtime](#container-runtime)_.
27
29
- An Integrated Developer Environment (IDE) or code editor, such as:
28
30
-[Visual Studio 2022](https://visualstudio.microsoft.com/vs/) version 17.9 or higher (Optional)
29
31
-[Visual Studio Code](https://code.visualstudio.com/) (Optional)
@@ -102,7 +104,7 @@ dotnet new install Aspire.ProjectTemplates::9.3.0
102
104
103
105
:::zone pivot="visual-studio"
104
106
105
-
The .NET Aspire templates are installed automatically when you install Visual Studio 17.9 or later. To see what .NET Aspire templates are available, select **File** > **New** > **Project** in Visual Studio, and search for "Aspire" in the search bar (<kbd>Alt</kbd>+<kbd>S</kbd>). You'll see a list of available .NET Aspire project templates:
107
+
The .NET Aspire templates are installed automatically when you install Visual Studio 17.9 or later. To see what .NET Aspire templates are available, select **File** > **New** > **Project** in Visual Studio, and search for "Aspire" in the search bar (<kbd>Alt</kbd>+<kbd>S</kbd>). You see a list of available .NET Aspire project templates:
106
108
107
109
:::image type="content" source="media/vs-create-dotnet-aspire-proj.png" alt-text="Visual Studio: Create new project and search for 'Aspire'." lightbox="media/vs-create-dotnet-aspire-proj.png":::
108
110
@@ -136,7 +138,12 @@ For more information, see [.NET Aspire templates](aspire-sdk-templates.md).
136
138
137
139
## Container runtime
138
140
139
-
.NET Aspire projects are designed to run in containers. You can use either Docker Desktop or Podman as your container runtime. [Docker Desktop](https://www.docker.com/products/docker-desktop/) is the most common container runtime. [Podman](https://podman.io/docs/installation) is an open-source daemonless alternative to Docker, that can build and run Open Container Initiative (OCI) containers. If your host environment has both Docker and Podman installed, .NET Aspire defaults to using Docker. You can instruct .NET Aspire to use Podman instead, by setting the `ASPIRE_CONTAINER_RUNTIME` environment variable to `podman`:
141
+
.NET Aspire can run containers using several OCI-compatible runtimes, including Docker Desktop and Podman. While some users have reported success using [Rancher Desktop](https://rancherdesktop.io/)—particularly when configured to use the Docker CLI—this isn't an officially supported or regularly tested scenario. It might be possible to use Rancher Desktop with the default installation, but it's not an officially supported or validated approach. If you encounter issues with Rancher Desktop, please let us know, but be aware that fixes might not be prioritized.
142
+
143
+
-[Docker Desktop](https://www.docker.com/products/docker-desktop/) is the most popular container runtime among .NET Aspire developers, offering a familiar and widely supported environment for building and running containers.
144
+
-[Podman](https://podman.io/docs/installation) is an open-source, daemonless alternative to Docker. It supports building and running Open Container Initiative (OCI) containers, making it a flexible choice for developers who prefer a lightweight solution.
145
+
146
+
If your host environment has a Docker and Podman installed, .NET Aspire defaults to using Docker. You can instruct .NET Aspire to use Podman instead, by setting the `DOTNET_ASPIRE_CONTAINER_RUNTIME` environment variable to `podman`:
140
147
141
148
## [Linux](#tab/linux)
142
149
@@ -174,7 +181,7 @@ The .NET Aspire dashboard is also available in a standalone mode. For more infor
174
181
175
182
## Visual Studio tooling
176
183
177
-
Visual Studio provides additional features for working with .NET Aspire integrations and the App Host orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI.
184
+
Visual Studio provides extra features for working with .NET Aspire integrations and the App Host orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI.
178
185
179
186
### Add an integration package
180
187
@@ -192,7 +199,7 @@ For more information on .NET Aspire integrations, see [.NET Aspire integrations
192
199
193
200
### Add hosting packages
194
201
195
-
.NET Aspire hosting packages are used to configure various resources and dependencies an app may depend on or consume. Hosting packages are differentiated from other integration packages in that they're added to the _*.AppHost_ project. To add a hosting package to your app, follow these steps:
202
+
.NET Aspire hosting packages are used to configure various resources and dependencies an app might depend on or consume. Hosting packages are differentiated from other integration packages in that they're added to the _*.AppHost_ project. To add a hosting package to your app, follow these steps:
196
203
197
204
1. In Visual Studio, right select on the _*.AppHost_ project and select **Add** > **.NET Aspire package...**.
![dotnet-policy-service[bot]](https://avatars.githubusercontent.com/in/285228?v=4&size=40){kind=avatar}
0 commit comments