[New article]: Document existing resource support in Aspire

[captainsafia]

Proposed topic or title

Referencing existing resources in Aspire

Location in table of contents.

/Integrations / Azure / Overview / Add connection to existing Azure resources

Reason for the article

In addition to the pre-existing AddConnectionString API, we're adding expanded support for being able to reference existing Azure resources in Aspire that we should document.

Article abstract

Below is a Copilot-generated/Safia-enhanced summary of the feature to help with documentation.

---

Documentation for PublishAsExisting and RunAsExisting APIs

Overview

The PublishAsExisting and RunAsExisting APIs are used to define and manage existing Azure resources within Aspire applications. They allow developers to reference already-deployed Azure resources, configure them, and generate appropriate deployment manifests using Bicep templates.

---

RunAsExisting

Purpose

The RunAsExisting method is used when a distributed application is running 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.

Example Usage

using var builder = DistributedApplication.CreateBuilder();

var existingResourceName = builder.AddParameter("existingResourceName");
var serviceBus = builder.AddAzureServiceBus("messaging")
    .RunAsExisting(existingResourceName)
    .WithQueue("queue");

---

PublishAsExisting

Purpose

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 faciliating the creation of manifests and templates that include resource definitions that map to existing resources in Bicep.

Example Usage

using var builder = DistributedApplication.CreateBuilder();

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

Generated Manifest Example

{
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingResourceName": "{existingResourceName.value}",
    "principalType": "",
    "principalId": ""
  }
}

Generated Bicep Template Example

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param existingResourceName string
param principalType string
param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingResourceName
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

---

AsExisting

Purpose

The AsExisting method is used when a distributed application is running in "Run" or "Publish" mode. Because the AsExisting method can operate in both scenarios, it can only support a parameterized reference to the resource name or resource group name.

Example Usage

using var builder = DistributedApplication.CreateBuilder();

var existingResourceName = builder.AddParameter("existingResourceName");
var serviceBus = builder.AddAzureServiceBus("messaging")
    .AsExisting(existingResourceName)
    .WithQueue("queue");

---

Use Cases

• 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.
• Use PublishAsExisting when declaring existing resources in both configurations, with a requirement to parameterize the references.

---

Additional Examples

Storage Account Example (with PublishAsExisting)

var storageAccount = builder.AddAzureStorage("storage")
    .PublishAsExisting("existingResourceName", "existingResourceGroupName");

Generated Manifest:

{
  "type": "azure.bicep.v1",
  "path": "storage.module.bicep",
  "params": {
    "existingResourceName": "{existingResourceName.value}",
    "principalType": "",
    "principalId": ""
  },
  "scope": {
    "resourceGroup": "{existingResourceGroupName.value}"
  }
}

Generated Bicep Template:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param existingResourceName string
param principalType string
param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' existing = {
  name: existingResourceName
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

---

Some additional notes on the RunAsExisting/PublishAsExisting APIs:

• They can consume the arguments as either ParameterResources or strings. Using ParameterResource allows the end-user to configure the target properties dynamically.
• They are supported on all Azure resource types, as of 9.1.
• The resourceGroup argument is optional. When it's not provided, the implementation will use an existing resource defined in the same resoruce group as the deployment.
• The name argument is always required.

Relevant searches

No response

---

Associated WorkItem - 375712

[captainsafia]

@IEvangelist Heads up for you on a new feature for 9.1.

I included a summary of the feature here but we likely don't need to be this wordy if we want something that matches the tone of the existing header.

[maddymontaquila]

@IEvangelist @alistairmatthews should we update the learn module that previously walked through this w the manifest? https://learn.microsoft.com/en-us/training/modules/customize-dotnet-aspire-existing-resources/