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
The following is a set of guidelines to follow when writing documentation for .NET Aspire. Please ensure that all documentation adheres to these guidelines:
2
+
3
+
## Voice and tone
4
+
5
+
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.
6
+
7
+
- Use active voice
8
+
- Use the second person (you, your) to address the reader directly
9
+
10
+
## Headings
11
+
12
+
Headings use sentence-style capitalization. Always capitalize the first word of a heading. Do not use gerunds (e.g., "Using" or "Creating") in heading.
13
+
14
+
## Text styling
15
+
16
+
Use _italics_ for files, folders, paths (for long items, split onto their own line), new terms.
17
+
18
+
Use **bold** for UI elements.
19
+
20
+
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.
21
+
22
+
## Links
23
+
24
+
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:
25
+
26
+
"For more information, see [link text](../relative/link/to/content.md)."
27
+
28
+
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`.
29
+
30
+
## Things to avoid
31
+
32
+
- 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.
33
+
- Avoid passive voice: Passive voice can make your writing less clear and harder to read. Use active voice whenever possible.
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.
2
+
3
+
Please also always [adhere to our writing style](adhere-to-writing-style.prompt.md).
description: Learn how to configure Azure Container Apps environments in .NET Aspire.
4
+
ms.topic: how-to
5
+
ms.date: 04/09/2025
6
+
---
7
+
8
+
# Configure Azure Container Apps environments
9
+
10
+
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:
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.
17
+
18
+
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.
19
+
20
+
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).
21
+
22
+
This article guides you through the process of tailoring ACA environments for your .NET Aspire solutions.
23
+
24
+
## Add an ACA environment
25
+
26
+
<!-- TODO: Add xref to AddAzureContainerAppEnvironment when available -->
27
+
28
+
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>).
- A user-assigned managed identity for the ACA environment.
39
+
- An Azure Container Registry (ACR) for the ACA environment.
40
+
- A Log Analytics workspace for the ACA environment.
41
+
- An Azure Container Apps environment.
42
+
- The [.NET Aspire dashboard](../fundamentals/dashboard/overview.md) for the ACA environment.
43
+
- A role assignment for the user principal ID to the ACA environment.
44
+
- Various outputs for the ACA environment.
45
+
46
+
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).
47
+
48
+
## Handle naming conventions
49
+
50
+
<!-- TODO: Add xref to WithAzdResourceNaming when available -->
51
+
52
+
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`:
Copy file name to clipboardExpand all lines: docs/azure/integrations-overview.md
+13-13
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Azure integrations overview
3
3
description: Overview of the Azure integrations available in the .NET Aspire.
4
-
ms.date: 03/07/2025
4
+
ms.date: 04/10/2025
5
5
uid: dotnet/aspire/integrations/azure-overview
6
6
---
7
7
@@ -107,7 +107,7 @@ You can query whether a resource is marked as an existing resource, by calling t
107
107
108
108
.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.
109
109
110
-
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.
110
+
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.
111
111
112
112
### Configure existing Azure resources for run mode
113
113
@@ -321,7 +321,7 @@ The preceding code:
321
321
- Adds an environment variable named `Hello` to the container app, using the `env` parameter.
322
322
- 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.
323
323
324
-
For more information, see <xref:Azure.Provisioning.AppContainers.ContainerApp> and <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.AsProvisioningParameter*>.
324
+
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*>.
325
325
326
326
## Infrastructure as code
327
327
@@ -462,27 +462,27 @@ By default, when you call any of the Bicep-related APIs, a call is also made to
462
462
463
463
Imagine that you have a Bicep template in a file named `storage.bicep` that provisions an Azure Storage Account:
To add a reference to the Bicep file on disk, call the <xref:Aspire.Hosting.AzureBicepResourceExtensions.AddBicepTemplate%2A> method. Consider the following example:
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.
472
472
473
473
#### Reference Bicep inline
474
474
475
475
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:
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.
480
480
481
481
#### Pass parameters to Bicep templates
482
482
483
483
[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:
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:
- The `webHookApi` project is added as a reference to the `builder`.
521
521
- 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
528
528
529
529
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`:
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:
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:
538
538
@@ -558,11 +558,11 @@ It's important to [avoid outputs for secrets](/azure/azure-resource-manager/bice
558
558
559
559
Consider the following Bicep template as an example the helps to demonstrate this concept of securing secret outputs:
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:
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.
0 commit comments