Add existing resources by IEvangelist · Pull Request #2642 · dotnet/docs-aspire

IEvangelist · 2025-02-19T17:01:18Z

Summary

New content detailing the AsExisting, RunAsExisting, and PublishAsExisting APIs.

Internal previews

📄 File	🔗 Preview link
docs/azure/integrations-overview.md	.NET Aspire Azure integrations overview
docs/fundamentals/app-host-overview.md	.NET Aspire orchestration overview
docs/messaging/nats-integration.md	.NET Aspire NATS integration
docs/whats-new/dotnet-aspire-9.1.md	What's new in .NET Aspire 9.1

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

* Adds the NATS 9.1 API and fixes obsolete API. Closes dotnet#1817 * Fix link

eerhardt · 2025-02-20T20:59:24Z

+> [!NOTE]
+> Not all APIs are available on all Azure resources. For example, some Azure resources can be containerized or emulated, while others cannot.
+
+When it comes to specifying whether an Azure resource in the app model is an existing resource, you can use the `AsExisting` API. The `AsExisting` method marks the resource as an existing resource in both run and publish modes. You can query whether a resource has been marked as an existing resource, by calling the `IsExisting` extension method on the <xref:Aspire.Hosting.ApplicationModel.IResource>. For more information, see [Mark Azure resources as existing](#mark-azure-resources-as-existing).


I feel like AsExisting should be in the table above. Was there a reason why it isn't?

I felt like it didn't belong since it does both modes, I suppose there could be a column with the applicable mode, or something?

Table would be fine. We'd also want somewhere to capture the info I shared in #2642 (comment). A table might get a little too stuffy if we added all that?

I think the info in #2642 (comment) belongs in a paragraph form here.

Having AsExisting in the table calls attention to it and puts it on the same level as RunAsExisting and PublishAsExisting. I think it belongs in the same spot(s).

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

eerhardt · 2025-02-20T21:07:05Z


 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 any and all role assignments for the target resource have been 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).

+## Mark Azure resources as existing


@captainsafia - what is your thoughts on moving this above Add existing Azure resources with connection strings?

I like that with this format we have a segue from the connection strings approach to the bicep one. Although it does make it seem like connection strings are preferred to bicep. We can consider re-arranging it and maybe making the connection string stuff an H3 under existing resources instead of an H2?

We can consider re-arranging it and maybe making the connection string stuff an H3 under existing resources instead of an H2?

I like this idea.

Although it does make it seem like connection strings are preferred to bicep.

Yes, that was my thinking. I think we should suggest using the new "Existing" feature first, because it works so much better and enables so many more scenarios.

How about we restructure/flow of the article to be the following (only looking at H2s and only highlighting changes to H3):

Naming conventions and APIs for expressing Azure resources

Add Azure resources

Mark Azure resources as existing

Add existing Azure resources with connection strings

Infrastructure as code

Publishing

Perhaps both the existing APIs bits and the connection string blurbs should be H3s, under the Add Azure resources heading? Thoughts? Admittedly, there are other H3s and H4s that were omitted from here.

I like moving the "as existing" and "connection string" stuff lower than the "typical devloper experience" stuff. We should have the normal cases first - when you add a new resource, not use an existing one. I also like having "as existing" above "connection string". So I think this proposal sounds good to me.

eerhardt · 2025-02-20T23:20:36Z

-The NATS JetStream functionality provides a built-in persistence engine called JetStream which enables messages to be stored and replayed at a later time. You can optionally provide a `srcMountPath` parameter to specify the path to the JetStream data directory on the host machine (the provided mount path maps to the container's `-sd` argument).
+The NATS JetStream functionality provides a built-in persistence engine called JetStream which enables messages to be stored and replayed at a later time.
+
+### Add NETS server resource with authentication parameters


Suggested change

### Add NETS server resource with authentication parameters

### Add NATS server resource with authentication parameters

These commits mistakenly came over from a rebase, I'll incorporate the feedback elsewhere. Thank you.

eerhardt · 2025-02-20T23:21:02Z

+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var username = builder.AddParameter("username", secret: true);


Suggested change

var username = builder.AddParameter("username", secret: true);

var username = builder.AddParameter("username");

Typically we don't mark usernames as secret...?

These commits mistakenly came over from a rebase, I'll incorporate the feedback elsewhere. Thank you.

eerhardt · 2025-02-21T00:28:21Z

+```csharp
+var builder = DistributedApplication.CreateBuilder();
+
+var existingResourceName = builder.AddParameter("existingResourceName");


Suggested change

var existingResourceName = builder.AddParameter("existingResourceName");

var existingResourceName = builder.AddParameter("existingServiceBusName");

?

eerhardt · 2025-02-21T00:29:46Z

+- Adds an Azure Service Bus resource named `messaging` to the builder.
+- Calls the `RunAsExisting` method on the `serviceBus` resource builder, passing the `existingResourceName` parameter—alternatively, you can use the `string` parameter overload.
+- Adds a queue named `queue` to the `serviceBus` resource.
+


We should add that the ServiceBus is assumed to be in the same Resource Group as your app is using.

eerhardt · 2025-02-21T00:33:54Z

+var serviceBus = builder.AddAzureServiceBus("messaging")
+    .PublishAsExisting(existingResourceName)
+    .WithQueue("queue");


Suggested change

var serviceBus = builder.AddAzureServiceBus("messaging")

.PublishAsExisting(existingResourceName)

.WithQueue("queue");

var serviceBus = builder.AddAzureServiceBus("messaging")

.PublishAsExisting(existingResourceName);

WithQueue was removed in 9.1

If you want to convert it, use:

var serviceBus = builder.AddAzureServiceBus("messaging") .PublishAsExisting(existingResourceName); serviceBus.AddServiceBusQueue("queue");

AddServiceBusQueue returns the queue resource. (Just like AddDatabase returns the child database resource)

See #2327 (comment)

Good catch, thanks for helping out with this.

Co-authored-by: Safia Abdalla <safia@safia.rocks>

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

davidfowl · 2025-02-21T15:51:38Z

We need to explain exactly how RunAsExisting and PublishAsExisting works (this is key to helping people understand and troubleshoot when things go wrong).

PublishAsExisting without a resource group is kinda pointless by default since we are creating a new resource group the first time you deploy. We should mention this somewhere…

eerhardt · 2025-02-21T16:05:17Z

PublishAsExisting without a resource group is kinda pointless by default since we are creating a new resource group the first time you deploy.

Does it make sense that resource group is an optional parameter then? It doesn't seem optional. cc @captainsafia

eerhardt · 2025-02-21T17:37:42Z

Does it make sense that resource group is an optional parameter then?

It should be possible to publish to an existing RG, right? https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/resource-group-scoped-deployments

But that case might be less common, so maybe it is better to require the dev to explicitly say null to mean "use current".

captainsafia · 2025-02-21T18:22:16Z

But that case might be less common, so maybe it is better to require the dev to explicitly say null to mean "use current".

I don't think we necessarily need to change the existing signatures in 9.1 to react to this. If we do, I'd prefer that we change to making the resource group a required parameter on the PublishAsExisting and AsExisting methods.

That being said, I think the immediate problem that @davidfowl is more about how explicit we want to be about what happens under the hood in the docs. Right now, we show the generated aspire-manifest and bicep definitions when you publish but don't necessarily explain what those deltas mean in the bigger context of the deployment.

IEvangelist · 2025-02-21T18:43:54Z

Closed by #2653

IEvangelist requested a review from captainsafia February 19, 2025 17:01

dotnetrepoman Bot added the fundamentals Content related to fundamentals. label Feb 19, 2025

eerhardt self-requested a review February 19, 2025 17:26

captainsafia reviewed Feb 19, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

captainsafia reviewed Feb 19, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

captainsafia reviewed Feb 19, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md

IEvangelist force-pushed the dotnet-aspire-9.1 branch from 44cfd4c to ca2baf7 Compare February 19, 2025 20:38

IEvangelist added 4 commits February 20, 2025 08:36

Add content for existing resources. Fixes dotnet#2549

672ed81

More links and details

532d9f5

Add missing emulators

d0c7cfc

Address feedback

c4b43c6

IEvangelist force-pushed the add-existing-resources branch from 40ae2c6 to c4b43c6 Compare February 20, 2025 14:56

captainsafia reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md

captainsafia reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

eerhardt reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/fundamentals/app-host-overview.md Outdated

eerhardt reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

IEvangelist and others added 5 commits February 20, 2025 14:52

Apply suggestions from code review

cf24bb5

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

[9.1] Add remove logs and telemetry to what's new (dotnet#2645)

aecf5a6

Adds the NATS 9.1 API and fixes obsolete API. (dotnet#2650)

fc98240

* Adds the NATS 9.1 API and fixes obsolete API. Closes dotnet#1817 * Fix link

A bit of clean up

f7aa850

Added details about the string overload.

d26cc3c

eerhardt reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

eerhardt reviewed Feb 20, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

Apply suggestions from code review

1a5e5d8

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

eerhardt reviewed Feb 20, 2025

View reviewed changes

eerhardt reviewed Feb 21, 2025

View reviewed changes

IEvangelist and others added 2 commits February 21, 2025 07:31

Apply suggestions from code review

1cad174

Co-authored-by: Safia Abdalla <safia@safia.rocks>

Update docs/azure/integrations-overview.md

03d68fb

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

IEvangelist commented Feb 21, 2025

View reviewed changes

Comment thread docs/azure/integrations-overview.md Outdated

Apply suggestions from code review

9e29761

IEvangelist mentioned this pull request Feb 21, 2025

Existing Azure resources #2653

Merged

IEvangelist closed this Feb 21, 2025

eerhardt mentioned this pull request Feb 21, 2025

[release/9.1] Require resource group on existing azure resources microsoft/aspire#7734

Merged


		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 any and all role assignments for the target resource have been 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).

		## Mark Azure resources as existing

	### Add NETS server resource with authentication parameters
	### Add NATS server resource with authentication parameters

	var username = builder.AddParameter("username", secret: true);
	var username = builder.AddParameter("username");

	var existingResourceName = builder.AddParameter("existingResourceName");
	var existingResourceName = builder.AddParameter("existingServiceBusName");

Conversation

IEvangelist commented Feb 19, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Internal previews

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eerhardt Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eerhardt Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidfowl commented Feb 21, 2025

Uh oh!

eerhardt commented Feb 21, 2025

Uh oh!

eerhardt commented Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

captainsafia commented Feb 21, 2025

Uh oh!

IEvangelist commented Feb 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

IEvangelist commented Feb 19, 2025 •

edited by github-actions Bot

Loading

eerhardt Feb 21, 2025 •

edited

Loading

eerhardt Feb 21, 2025 •

edited

Loading

eerhardt commented Feb 21, 2025 •

edited

Loading