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
Copy file name to clipboardExpand all lines: README.md
+1-3
Original file line number
Diff line number
Diff line change
@@ -11,8 +11,7 @@
11
11
12
12
This repository contains the conceptual documentation for .NET Aspire. The [.NET Aspire documentation site](https://learn.microsoft.com/dotnet/aspire).
@@ -33,7 +32,6 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
33
32
-[](https://github.com/dotnet/docs-aspire/actions/workflows/live-protection.yml): Adds a comment to PRs that were not automated, but rather manually created that target the `live` branch.
34
33
-[](https://github.com/dotnet/docs-aspire/actions/workflows/stale.yml): Closes stale issues that have not been updated in 180 days.
35
34
-[](https://github.com/dotnet/docs-aspire/actions/workflows/markdownlint.yml): The current status for the entire repositories Markdown linter status.
36
-
-[](https://github.com/dotnet/docs-aspire/actions/workflows/no-response.yml): If an issue is labeled with `needs-more-info` and the op doesn't respond within 14 days, the issue is closed.
37
35
-[](https://github.com/dotnet/docs-aspire/actions/workflows/check-for-build-warnings.yml): Builds the site for the PR in context, and verifies the build reporting either, `success,``warnings`, or `error`.
38
36
-[](https://github.com/dotnet/docs-aspire/actions/workflows/snippets5000.yml): Custom .NET build validation, locates code impacted by a PR, and builds.
39
37
-[](https://github.com/dotnet/docs-aspire/actions/workflows/version-sweep.yml): Runs monthly, creating issues on projects that target .NET versions that are out of support.
Copy file name to clipboardExpand all lines: docs/azure/integrations-overview.md
+15-9
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: 02/21/2025
4
+
ms.date: 02/25/2025
5
5
uid: dotnet/aspire/integrations/azure-overview
6
6
---
7
7
@@ -77,9 +77,9 @@ For more information on the difference between run and publish modes, see [.NET
77
77
78
78
### APIs for expressing Azure resources in different modes
79
79
80
-
The distributed application builder, part of the [app host](../fundamentals/app-host-overview.md), employs the builder pattern, allowing consumers to `AddAzure*` resources to the [_app model_](../fundamentals/app-host-overview.md#terminology). In addition to simply adding resources, developers can also express configuration and how said resource behave in various execution contexts. Azure hosting integrations provide APIs to specify how these resources should be "published" and "run".
80
+
The distributed application builder, part of the [app host](../fundamentals/app-host-overview.md), uses the builder patternto `AddAzure*` resources to the [_app model_](../fundamentals/app-host-overview.md#terminology). Developers can configure these resourcesand define their behavior in different execution contexts. Azure hosting integrations provide APIs to specify how these resources should be "published" and "run".
81
81
82
-
When the app host executes, the [_execution context_](../fundamentals/app-host-overview.md#execution-context)determines whether the app host is in <xref:Aspire.Hosting.DistributedApplicationOperation.Run> or <xref:Aspire.Hosting.DistributedApplicationOperation.Publish> mode. The naming conventions for these APIs indicate the intended action for the resource. For more information on execution modes, see [Execution context](../fundamentals/app-host-overview.md#execution-context).
82
+
When the app host executes, the [_execution context_](../fundamentals/app-host-overview.md#execution-context)is used to determine whether the app host is in <xref:Aspire.Hosting.DistributedApplicationOperation.Run> or <xref:Aspire.Hosting.DistributedApplicationOperation.Publish> mode. The naming conventions for these APIs indicate the intended action for the resource.
83
83
84
84
The following table summarizes the naming conventions used to express Azure resources:
85
85
@@ -95,19 +95,23 @@ The following table summarizes the naming conventions used to express Azure reso
95
95
> [!NOTE]
96
96
> Not all APIs are available on all Azure resources. For example, some Azure resources can be containerized or emulated, while others can't.
97
97
98
+
For more information on execution modes, see [Execution context](../fundamentals/app-host-overview.md#execution-context).
99
+
98
100
#### General run mode API use cases
99
101
100
-
Use `RunAsExisting` when you need to dynamically interact with an existing resource during runtime without needing to deploy or update it. Use `PublishAsExisting` when declaring existing resources as part of a deployment configuration, ensuring the correct scopes and permissions are applied. Finally, use `AsExisting` when declaring existing resources in both configurations, with a requirement to parameterize the references.
102
+
Use <xref:Aspire.Hosting.ExistingAzureResourceExtensions.RunAsExisting*> when you need to dynamically interact with an existing resource during runtime without needing to deploy or update it. Use <xref:Aspire.Hosting.ExistingAzureResourceExtensions.PublishAsExisting*> when declaring existing resources as part of a deployment configuration, ensuring the correct scopes and permissions are applied. Finally, use <xref:Aspire.Hosting.ExistingAzureResourceExtensions.AsExisting``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.ParameterResource},Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.ParameterResource})> when declaring existing resources in both configurations, with a requirement to parameterize the references.
101
103
102
-
You can query whether a resource is marked as an existing resource, by calling the `IsExisting` extension method on the <xref:Aspire.Hosting.ApplicationModel.IResource>. For more information, see [Use existing Azure resources](#use-existing-azure-resources).
104
+
You can query whether a resource is marked as an existing resource, by calling the <xref:Aspire.Hosting.ExistingAzureResourceExtensions.IsExisting(Aspire.Hosting.ApplicationModel.IResource)> extension method on the <xref:Aspire.Hosting.ApplicationModel.IResource>. For more information, see [Use existing Azure resources](#use-existing-azure-resources).
103
105
104
106
## Use existing Azure resources
105
107
106
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.
107
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.
111
+
108
112
### Configure existing Azure resources for run mode
109
113
110
-
The `RunAsExisting` method is used when a distributed application is executing in "run" mode. In this mode, it assumes that the referenced Azure resource already exists and integrates with it during execution without provisioning the resource. To mark an Azure resource as existing, call the `RunAsExisting` method on the resource builder. Consider the following example:
114
+
The <xref:Aspire.Hosting.ExistingAzureResourceExtensions.RunAsExisting*> method is used when a distributed application is executing in "run" mode. In this mode, it assumes that the referenced Azure resource already exists and integrates with it during execution without provisioning the resource. To mark an Azure resource as existing, call the `RunAsExisting` method on the resource builder. Consider the following example:
@@ -133,7 +137,7 @@ By default, the Service Bus parameter reference is assumed to be in the same Azu
133
137
134
138
### Configure existing Azure resources for publish mode
135
139
136
-
The `PublishAsExisting` method is used in "publish" mode when the intent is to declare and reference an already-existing Azure resource during publish mode. This API facilitates the creation of manifests and templates that include resource definitions that map to existing resources in Bicep.
140
+
The <xref:Aspire.Hosting.ExistingAzureResourceExtensions.PublishAsExisting*> method is used in "publish" mode when the intent is to declare and reference an already-existing Azure resource during publish mode. This API facilitates the creation of manifests and templates that include resource definitions that map to existing resources in Bicep.
137
141
138
142
To mark an Azure resource as existing in for the "publish" mode, call the `PublishAsExisting` method on the resource builder. Consider the following example:
139
143
@@ -217,9 +221,9 @@ For more information on the generated Bicep template, see [Infrastructure as cod
217
221
> [!WARNING]
218
222
> When interacting with existing resources that require authentication, ensure the authentication strategy that you're configuring in the .NET Aspire application model aligns with the authentication strategy allowed by the existing resource. For example, it's not possible to use managed identity against an existing Azure PostgreSQL resource that isn't configured to allow managed identity. Similarly, if an existing Azure Redis resource disabled access keys, it's not possible to use access key authentication.
219
223
220
-
### Configure existing Azure resources
224
+
### Configure existing Azure resources in all modes
221
225
222
-
The `AsExisting` method is used when the distributed application is running in "run" or "publish" mode. Because the `AsExisting` method operates in both scenarios, it only supports a parameterized reference to the resource name or resource group name. This approach helps prevent the use of the same resource in both testing and production environments.
226
+
The <xref:Aspire.Hosting.ExistingAzureResourceExtensions.AsExisting``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.ParameterResource},Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.ParameterResource})> method is used when the distributed application is running in "run" or "publish" mode. Because the `AsExisting` method operates in both scenarios, it only supports a parameterized reference to the resource name or resource group name. This approach helps prevent the use of the same resource in both testing and production environments.
223
227
224
228
To mark an Azure resource as existing, call the `AsExisting` method on the resource builder. Consider the following example:
225
229
@@ -274,6 +278,8 @@ The preceding code:
274
278
275
279
The consuming API project uses the connection string information with no knowledge of how the app host configured it. In "publish" mode, the code adds a new Azure Storage resource—which would be reflected in the [deployment manifest](../deployment/manifest-format.md) accordingly. When in "run" mode the connection string corresponds to a configuration value visible to the app host. It's assumed that all role assignments for the target resource are configured. This means, you'd likely configure an environment variable or a user secret to store the connection string. The configuration is resolved from the `ConnectionStrings__storage` (or `ConnectionStrings:storage`) configuration key. These configuration values can be viewed when the app runs. For more information, see [Resource details](../fundamentals/dashboard/explore.md#resource-details).
276
280
281
+
Unlike existing resources modeled with [the first-class `AsExisting` API](#use-existing-azure-resources), existing resource modeled as connection strings cannot be enhanced with additional role assignments or infrastructure customizations.
282
+
277
283
## Infrastructure as code
278
284
279
285
The Azure SDK for .NET provides the [📦 Azure.Provisioning](https://www.nuget.org/packages/Azure.Provisioning) NuGet package and a suite of service-specific [Azure provisioning packages](https://www.nuget.org/packages?q=owner%3A+azure-sdk+description%3A+declarative+resource+provisioning&sortby=relevance). These Azure provisioning libraries make it easy to declaratively specify Azure infrastructure natively in .NET. Their APIs enable you to write object-oriented infrastructure in C#, resulting in Bicep. [Bicep is a domain-specific language (DSL)](/azure/azure-resource-manager/bicep/overview) for deploying Azure resources declaratively.
Copy file name to clipboardExpand all lines: docs/extensibility/snippets/MailDevResource/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj
Copy file name to clipboardExpand all lines: docs/extensibility/snippets/MailDevResourceAndComponent/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj
Copy file name to clipboardExpand all lines: docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj
![dotnet-policy-service[bot]](https://avatars.githubusercontent.com/in/285228?v=4&size=40){kind=avatar}
0 commit comments