✅ Merge main into live

.github/copilot-instructions.md

@@ -0,0 +1,41 @@
+When writing documentation or editing .md files, follow the following guidelines:
+
+Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
+
+Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+
+Headings should be in sentence case, not title case. Don't use gerunds in titles.
+
+Use the active voice whenever possible, and second person to address the reader directly.
+
+Use a conversational tone with contractions.
+
+Be concise.
+
+Break up long sentences.
+
+Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
+
+Do not use "we" or "our" to refer to the authors of the documentation.
+
+Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method."
+
+Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception."
+
+Use the Oxford comma in lists of three or more items.
+
+Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists.
+
+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.
+
+Put raw URLs within angle brackets.
+
+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.
+
+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>.
+
+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.
+
+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.
+
+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.

.github/prompts/breaking-change.md

@@ -0,0 +1,61 @@
+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:
+
+The document should be in Markdown format.
+
+.NET Aspire breaking changes live in the https://github.com/dotnet/docs-aspire/tree/main/docs/compatibility folder and its subfolders.
+
+Rephrase all content to be clear and concise, if necessary.
+
+Describe previous behavior in past tense and new behavior in present tense.
+
+The document should start with the following frontmatter, including `---` characters. Placeholder text is shown in angle brackets.
+
+   ---
+   title: "Breaking change - <A concise descriptive title of the breaking change>"
+   description: "Learn about the breaking change in <product/version without the preview number> where <very brief description>."
+   ms.date: <Today's date>
+   ai-usage: ai-assisted
+   ms.custom: <URL of the GitHub issue>
+   ---
+
+After the frontmatter, include the following sections in this order. Use the description in parentheses as a guide for the content of each section.
+
+h1: "(The same title used in the document header, sans 'Breaking Change - ')"
+
+   (An introductory paragraph summarizing the breaking change. Include the major version but not the preview number.)
+
+h2: Version introduced
+
+   (The version in which the breaking change was introduced. Include the preview number here, if given.)
+
+h2: Previous behavior
+
+   (A brief description of the behavior before the change, including an example code snippet if applicable.)
+
+h2: New behavior
+
+   (A brief description of the behavior after the change, including an example code snippet if applicable.)
+
+h2: Type of breaking change
+
+   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).`
+
+   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).`
+
+   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."
+
+h2: Reason for change
+
+   (The complete reasoning behind the change, including any relevant links.)
+
+h2: Recommended action
+
+   (A brief description of the action or actions that users should take, including example code snippets if applicable.)
+
+h2: Affected APIs
+
+   (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>".)
+
+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).
+
+Next, create a pull request. In the description, include the text "Fixes #\<issue-number>", where "issue-number" is the GitHub issue number.

docs/fundamentals/setup-tooling.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire tooling
 description: Learn about essential tooling concepts for .NET Aspire.
-ms.date: 04/15/2025
+ms.date: 05/30/2025
 zone_pivot_groups: dev-environment
 uid: dotnet/aspire/setup-tooling
 ---
@@ -23,7 +23,9 @@ To work with .NET Aspire, you need the following installed locally:
 
 - [.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or [.NET 9.0](https://dotnet.microsoft.com/download/dotnet/9.0).
 - An OCI compliant container runtime, such as:
-  - [Docker Desktop](https://www.docker.com/products/docker-desktop) or [Podman](https://podman.io/). For more information, see [Container runtime](#container-runtime).
+  - [Docker Desktop](https://www.docker.com/products/docker-desktop)
+  - [Podman](https://podman.io/)
+    - _For more information, see [Container runtime](#container-runtime)_.
 - An Integrated Developer Environment (IDE) or code editor, such as:
   - [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) version 17.9 or higher (Optional)
   - [Visual Studio Code](https://code.visualstudio.com/) (Optional)
@@ -102,7 +104,7 @@ dotnet new install Aspire.ProjectTemplates::9.3.0
 
 :::zone pivot="visual-studio"
 
-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:
+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:
 
 :::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":::
 
@@ -136,7 +138,12 @@ For more information, see [.NET Aspire templates](aspire-sdk-templates.md).
 
 ## Container runtime
 
-.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`:
+.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.
+
+- [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.
+- [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.
+
+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`:
 
 ## [Linux](#tab/linux)
 
@@ -174,7 +181,7 @@ The .NET Aspire dashboard is also available in a standalone mode. For more infor
 
 ## Visual Studio tooling
 
-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.
+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.
 
 ### Add an integration package
 
@@ -192,7 +199,7 @@ For more information on .NET Aspire integrations, see [.NET Aspire integrations
 
 ### Add hosting packages
 
-.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:
+.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:
 
 1. In Visual Studio, right select on the _*.AppHost_ project and select **Add** > **.NET Aspire package...**.
 

docs/index.yml

@@ -11,7 +11,7 @@ metadata:
   description: Learn about .NET Aspire, a cloud-ready stack for building distributed applications. Browse API reference, tutorials, and more.
   ms.topic: hub-page
   ms.service: dotnet-aspire
-  ms.date: 02/25/2025
+  ms.date: 05/30/2025
 
 highlightedContent:
   items:
@@ -360,7 +360,7 @@ additionalContent:
     items:
     - title: ".NET Aspire API reference"
       summary: API reference documentation for .NET Aspire
-      url: /dotnet/api?view=dotnet-aspire-9.2&preserve-view=true
+      url: /dotnet/api?view=dotnet-aspire-9.3&preserve-view=true
     - title: ".NET API reference"
       summary: API reference documentation for .NET
       url: /dotnet/api?view=net-9.0&preserve-view=true

docs/toc.yml

@@ -226,9 +226,9 @@ items:
       displayName: web pubsub,real-time,messaging
       href: messaging/azure-web-pubsub-integration.md
     - name: Aspire.Hosting.Azure API reference
-      href: /dotnet/api/?term=Aspire.Hosting.Azure&view=dotnet-aspire-9.2&preserve-view=true
+      href: /dotnet/api/?term=Aspire.Hosting.Azure&view=dotnet-aspire-9.3&preserve-view=true
     - name: Aspire.Azure API reference
-      href: /dotnet/api/?term=Aspire.Azure&view=dotnet-aspire-9.2&preserve-view=true
+      href: /dotnet/api/?term=Aspire.Azure&view=dotnet-aspire-9.3&preserve-view=true
   - name: Elasticsearch
     displayName: elasticsearch,search
     href: search/elasticsearch-integration.md
@@ -371,7 +371,7 @@ items:
     - name: RavenDB
       href: community-toolkit/ravendb.md
   - name: Aspire.Hosting API reference
-    href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.2&preserve-view=true
+    href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.3&preserve-view=true
 
 - name: Custom integrations
   items:
@@ -507,7 +507,7 @@ items:
         - name: Publishing to Azure APIs are experimental
           href: diagnostics/aspireazure001.md
   - name: .NET Aspire API reference
-    href: /dotnet/api?view=dotnet-aspire-9.2&preserve-view=true
+    href: /dotnet/api?view=dotnet-aspire-9.3&preserve-view=true
   - name: .NET Aspire FAQ
     displayName: iis,functions,deploy,azure,kubernetes
     href: reference/aspire-faq.yml