dotnet · IEvangelist · Apr 10, 2025 · Mar 19, 2025 · Mar 21, 2025 · Mar 21, 2025
@@ -0,0 +1,33 @@
+The following is a set of guidelines to follow when writing documentation for .NET Aspire. Please ensure that all documentation adheres to these guidelines:
+
+## Voice and tone
+
+Write for readers who may have a limited vocabulary or are not native English speakers. Use simple, clear language and avoid jargon whenever possible. If you must use technical terms, provide a brief explanation of what they mean.
+
+- Use active voice
+- Use the second person (you, your) to address the reader directly
+
+## Headings
+
+Headings use sentence-style capitalization. Always capitalize the first word of a heading. Do not use gerunds (e.g., "Using" or "Creating") in heading.
+
+## Text styling
+
+Use _italics_ for files, folders, paths (for long items, split onto their own line), new terms.
+
+Use **bold** for UI elements.
+
+Use `code` for inline code, language keywords, NuGet package names, command-line commands, database table and column names, and URLs that you don't want to be clickable.
+
+## Links
+
+Strive to use relative links whenever possible. Use absolute links only when necessary. For example, if you are linking to a page on a different site, use an absolute link. When using absolute links, use the full URL (including the protocol) and remove the locale from the URL. Avoid HTTP links, always prefer HTTPS. Whenever providing additional resources, use the following format:
+
+"For more information, see [link text](../relative/link/to/content.md)."
+
+Never link to `https://learn.microsoft.com` or `https://learn.microsoft.com/en-us`, always remove these and instead use site relative links. For example, if the original link is `https://learn.microsoft.com/en-us/aspnet/core/mvc/overview`, it should be changed to `/aspnet/core/mvc/overview`.
+
+## Things to avoid
+
+- Avoid future tense: In some non-English languages the concept of future tense is not the same as English. Using future tense can make your documents harder to read.
+- Avoid passive voice: Passive voice can make your writing less clear and harder to read. Use active voice whenever possible.
@@ -0,0 +1,3 @@
+Please rephrase the selected text to make it more concise and clear, while maintaining the original meaning. The rephrased text should strive to improve readability. Please ensure that the rephrased text is grammatically correct and flows well. Take obvious opportunities to improve structure, and emphasis of domain specific intent.
+
+Please also always [adhere to our writing style](adhere-to-writing-style.prompt.md).
@@ -34,6 +34,9 @@ _dependentPackages/
 !/xml/System.IO.Log/
 !/xml/System.Net.Cache/
 
+# Playwright dependencies
+**/*/playwright-deps
+
 # Visual Studio Code
 .vscode/*
 !.vscode/extensions.json

@@ -1,13 +1,12 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <IsAspireHost>true</IsAspireHost>
     <UserSecretsId>7b352f08-305b-4032-9a21-90deb02efc04</UserSecretsId>
   </PropertyGroup>
 
@@ -17,8 +16,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
-    <PackageReference Include="Aspire.Hosting.Redis" Version="9.1.0" />
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.2.0" />
+    <PackageReference Include="Aspire.Hosting.Redis" Version="9.2.0" />
   </ItemGroup>
 
 </Project>
@@ -1,13 +1,12 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <IsAspireHost>true</IsAspireHost>
     <UserSecretsId>7b352f08-305b-4032-9a21-90deb02efc04</UserSecretsId>
   </PropertyGroup>
 
@@ -17,8 +16,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
-    <PackageReference Include="Aspire.Hosting.Redis" Version="9.1.0" />
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.2.0" />
+    <PackageReference Include="Aspire.Hosting.Redis" Version="9.2.0" />
   </ItemGroup>
 
 </Project>
@@ -11,7 +11,7 @@
     <FrameworkReference Include="Microsoft.AspNetCore.App" />
 
     <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.4.0" />
-    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.1.0" />
+    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.2.0" />
     <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.2" />
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.1" />

@@ -11,7 +11,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Aspire.StackExchange.Redis.OutputCaching" Version="9.1.0" />
+    <PackageReference Include="Aspire.StackExchange.Redis.OutputCaching" Version="9.2.0" />
   </ItemGroup>
 
 </Project>
@@ -1,13 +1,12 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <IsAspireHost>true</IsAspireHost>
     <UserSecretsId>10daccf5-26f1-4641-80b2-95f0357607cf</UserSecretsId>
   </PropertyGroup>
 
@@ -17,7 +16,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.2.0" />
     <PackageReference Include="Aspire.Hosting.Keycloak" Version="9.1.0-preview.1.24113.4 />
   </ItemGroup>
 

@@ -11,7 +11,7 @@
     <FrameworkReference Include="Microsoft.AspNetCore.App" />
 
     <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.4.0" />
-    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.1.0" />
+    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.2.0" />
     <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.2" />
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.1" />

@@ -0,0 +1,70 @@
+---
+title: Configure Azure Container Apps environments
+description: Learn how to configure Azure Container Apps environments in .NET Aspire.
+ms.topic: how-to
+ms.date: 04/09/2025
+---
+
+# Configure Azure Container Apps environments
+
+It's easy to [publish resources as Azure Container Apps (ACA)](integrations-overview.md#publish-as-azure-container-app) using any of the supported APIs:
+
+- <xref:Aspire.Hosting.AzureContainerAppProjectExtensions.PublishAsAzureContainerApp*?displayProperty=nameWithType>
+- <xref:Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp*?displayProperty=nameWithType>
+- <xref:Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp*?displayProperty=nameWithType>
+
+These APIs automatically create a default ACA environment when you publish your app. While this default setup works well for most scenarios, you might need to customize the ACA environment to meet specific requirements. To achieve this, use the `AddAzureContainerAppEnvironment` method.
+
+The [.NET Aspire app host](../fundamentals/app-host-overview.md) simplifies infrastructure provisioning by generating code to create Azure resources for your applications. This approach enables you to model and configure deployment-related aspects directly in C#, reducing the need to rely on tools like Bicep. These aspects include configuring ACA environments, which provide a serverless platform for running containerized applications.
+
+By using the <xref:Azure.Provisioning> APIs (explained in [Infrastructure as code](integrations-overview.md#infrastructure-as-code)), you can configure and customize ACA environments along with related resources, such as container registries and file share volumes. Any available deployment setting can be configured. For more information on the available settings, see [Microsoft.App managedEnvironments](/azure/templates/microsoft.app/managedenvironments).
+
+This article guides you through the process of tailoring ACA environments for your .NET Aspire solutions.
+
+## Add an ACA environment
+
+<!-- TODO: Add xref to AddAzureContainerAppEnvironment when available -->
+
+The `AzureContainerAppEnvironmentResource` type models an ACA environment resource. When you call the `AddAzureContainerAppEnvironment` method, it creates an instance of this type (wrapped in the <xref:Aspire.Hosting.ApplicationModel.IResourceBuilder`1>).
+
+:::code language="csharp" source="snippets/aca/AspireAca.AppHost/AspireApp.AppHost/Program.cs":::
+
+By default, the calling this API to add an ACA environment generates the following provisioning Bicep module:
+
+:::code language="bicep" source="snippets/aca/AspireAca.AppHost/AspireApp.AppHost/aca-env.module.bicep":::
+
+This module configures:
+
+- A user-assigned managed identity for the ACA environment.
+- An Azure Container Registry (ACR) for the ACA environment.
+- A Log Analytics workspace for the ACA environment.
+- An Azure Container Apps environment.
+- The [.NET Aspire dashboard](../fundamentals/dashboard/overview.md) for the ACA environment.
+- A role assignment for the user principal ID to the ACA environment.
+- Various outputs for the ACA environment.
+
+Using the `acaEnv` variable, you can chain a call to the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure*> API to customize the ACA environment to your liking. For more information, see [Configure infrastructure](integrations-overview.md#configure-infrastructure).
+
+## Handle naming conventions
+
+<!-- TODO: Add xref to WithAzdResourceNaming when available -->
+
+By default, `AddAzureContainerAppEnvironment` uses a different Azure resource naming scheme than the [Azure Developer CLI (`azd`)](/azure/developer/azure-developer-cli/). If you're upgrading an existing deployment that previously used `azd`, you might see duplicate Azure resources. To avoid this issue, call the `WithAzdResourceNaming` method to revert to the naming convention used by `azd`:
+
+```csharp
+var builder = DistributionApplicationBuilder.Create(args);
+
+var acaEnv = builder.AddAzureContainerAppEnvironment("aca-env")
+                    .WithAzdResourceNaming();
+
+// Omitted for brevity...
+
+builder.Build().Run();
+```
+
+Calling this API ensures your existing Azure resources remain consistent and prevents duplication.
+
+## See also
+
+- [.NET Aspire Azure integrations overview](integrations-overview.md)
+- [Azure Container Apps overview](/azure/container-apps/overview)
@@ -1,7 +1,7 @@
 ---
 title: Azure integrations overview
 description: Overview of the Azure integrations available in the .NET Aspire.
-ms.date: 03/07/2025
+ms.date: 04/10/2025
 uid: dotnet/aspire/integrations/azure-overview
 ---
 
@@ -107,7 +107,7 @@ You can query whether a resource is marked as an existing resource, by calling t
 
 .NET Aspire provides support for referencing existing Azure resources. You mark an existing resource through the `PublishAsExisting`, `RunAsExisting`, and `AsExisting` APIs. These APIs allow developers to reference already-deployed Azure resources, configure them, and generate appropriate deployment manifests using Bicep templates.
 
-Existing resources referenced with these APIs can be enhanced with role assignments and other customizations that are available with .NET Aspire's [infrastructure as code capabilities](#infrastructure-as-code). These APIs are limited to Azure resources that can be deployed with Bicep templates.
+Existing resources referenced with these APIs can be enhanced with [role assignments](role-assignments.md) and other customizations that are available with .NET Aspire's [infrastructure as code capabilities](#infrastructure-as-code). These APIs are limited to Azure resources that can be deployed with Bicep templates.
 
 ### Configure existing Azure resources for run mode
 
@@ -321,7 +321,7 @@ The preceding code:
   - Adds an environment variable named `Hello` to the container app, using the `env` parameter.
   - The `AsProvisioningParameter` method is used to treat `env` as either a new <xref:Azure.Provisioning.ProvisioningParameter> in infrastructure, or reuses an existing bicep parameter if one with the same name already exists.
 
-For more information, see <xref:Azure.Provisioning.AppContainers.ContainerApp> and <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.AsProvisioningParameter*>.
+To configure the Azure Container App environment, see [Configure Azure Container Apps environments](configure-aca-environments.md). For more information, see <xref:Azure.Provisioning.AppContainers.ContainerApp> and <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.AsProvisioningParameter*>.
 
 ## Infrastructure as code
 
@@ -462,27 +462,27 @@ By default, when you call any of the Bicep-related APIs, a call is also made to
 
 Imagine that you have a Bicep template in a file named `storage.bicep` that provisions an Azure Storage Account:
 
-:::code language="bicep" source="snippets/AppHost.Bicep/storage.bicep":::
+:::code language="bicep" source="snippets/bicep/AppHost.Bicep/storage.bicep":::
 
 To add a reference to the Bicep file on disk, call the <xref:Aspire.Hosting.AzureBicepResourceExtensions.AddBicepTemplate%2A> method. Consider the following example:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.ReferenceBicep.cs" id="addfile":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.ReferenceBicep.cs" id="addfile":::
 
 The preceding code adds a reference to a Bicep file located at `../infra/storage.bicep`. The file paths should be relative to the _app host_ project. This reference results in an <xref:Aspire.Hosting.Azure.AzureBicepResource> being added to the application's resources collection with the `"storage"` name, and the API returns an `IResourceBuilder<AzureBicepResource>` instance that can be used to further customize the resource.
 
 #### Reference Bicep inline
 
 While having a Bicep file on disk is the most common scenario, you can also add Bicep templates inline. Inline templates can be useful when you want to define a template in code or when you want to generate the template dynamically. To add an inline Bicep template, call the <xref:Aspire.Hosting.AzureBicepResourceExtensions.AddBicepTemplateString%2A> method with the Bicep template as a `string`. Consider the following example:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.InlineBicep.cs" id="addinline":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.InlineBicep.cs" id="addinline":::
 
 In this example, the Bicep template is defined as an inline `string` and added to the application's resources collection with the name `"ai"`. This example provisions an Azure AI resource.
 
 #### Pass parameters to Bicep templates
 
 [Bicep supports accepting parameters](/azure/azure-resource-manager/bicep/parameters), which can be used to customize the behavior of the template. To pass parameters to a Bicep template from .NET Aspire, chain calls to the <xref:Aspire.Hosting.AzureBicepResourceExtensions.WithParameter%2A> method as shown in the following example:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.PassParameter.cs" id="addparameter":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.PassParameter.cs" id="addparameter":::
 
 The preceding code:
 
@@ -511,11 +511,11 @@ To use a well-known parameter, pass the parameter name to the <xref:Aspire.Hosti
 
 Consider an example where you want to set up an Azure Event Grid webhook. You might define the Bicep template as follows:
 
- :::code language="bicep" source="snippets/AppHost.Bicep/event-grid-webhook.bicep" highlight="3-4,27-35":::
+ :::code language="bicep" source="snippets/bicep/AppHost.Bicep/event-grid-webhook.bicep" highlight="3-4,27-35":::
 
 This Bicep template defines several parameters, including the `topicName`, `webHookEndpoint`, `principalId`, `principalType`, and the optional `location`. To pass these parameters to the Bicep template, you can use the following code snippet:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.PassParameter.cs" id="addwellknownparams":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.PassParameter.cs" id="addwellknownparams":::
 
 - The `webHookApi` project is added as a reference to the `builder`.
 - The `topicName` parameter is passed a hardcoded name value.
@@ -528,11 +528,11 @@ The well-known parameters are convention-based and shouldn't be accompanied with
 
 In addition to passing parameters to Bicep templates, you can also get outputs from the Bicep templates. Consider the following Bicep template, as it defines an `output` named `endpoint`:
 
-:::code language="bicep" source="snippets/AppHost.Bicep/storage-out.bicep":::
+:::code language="bicep" source="snippets/bicep/AppHost.Bicep/storage-out.bicep":::
 
 The Bicep defines an output named `endpoint`. To get the output from the Bicep template, call the <xref:Aspire.Hosting.AzureBicepResourceExtensions.GetOutput%2A> method on an `IResourceBuilder<AzureBicepResource>` instance as demonstrated in following C# code snippet:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.GetOutputReference.cs" id="getoutput":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.GetOutputReference.cs" id="getoutput":::
 
 In this example, the output from the Bicep template is retrieved and stored in an `endpoint` variable. Typically, you would pass this output as an environment variable to another resource that relies on it. For instance, if you had an ASP.NET Core Minimal API project that depended on this endpoint, you could pass the output as an environment variable to the project using the following code snippet:
 
@@ -558,11 +558,11 @@ It's important to [avoid outputs for secrets](/azure/azure-resource-manager/bice
 
 Consider the following Bicep template as an example the helps to demonstrate this concept of securing secret outputs:
 
-:::code language="bicep" source="snippets/AppHost.Bicep/cosmosdb.bicep" highlight="2,41":::
+:::code language="bicep" source="snippets/bicep/AppHost.Bicep/cosmosdb.bicep" highlight="2,41":::
 
 The preceding Bicep template expects a `keyVaultName` parameter, among several other parameters. It then defines an Azure Cosmos DB resource and stashes a secret into Azure Key Vault, named `connectionString` which represents the fully qualified connection string to the Cosmos DB instance. To access this secret connection string value, you can use the following code snippet:
 
-:::code language="csharp" source="snippets/AppHost.Bicep/Program.cs" id="secrets":::
+:::code language="csharp" source="snippets/bicep/AppHost.Bicep/Program.cs" id="secrets":::
 
 In the preceding code snippet, the `cosmos` Bicep template is added as a reference to the `builder`. The `connectionString` secret output is retrieved from the Bicep template and stored in a variable. The secret output is then passed as an environment variable (`ConnectionStrings__cosmos`) to the `api` project. This environment variable is used to connect to the Cosmos DB instance.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Please rephrase the selected text to make it more concise and clear, while maintaining the original meaning. The rephrased text should strive to improve readability. Please ensure that the rephrased text is grammatically correct and flows well. Take obvious opportunities to improve structure, and emphasis of domain specific intent.

		Please also always [adhere to our writing style](adhere-to-writing-style.prompt.md).