Recommend AsExisting() for Azure Integrations

docs/azureai/azureai-openai-integration.md

@@ -125,34 +125,8 @@ builder.AddProject<Projects.ExampleProject>()
 
 For more information on treating Azure OpenAI resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources).
 
-Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the app host. Which is a weakly-typed approach that's based solely on a `string` value. To add a connection to an existing Azure OpenAI service, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString%2A> method:
-
-```csharp
-var builder = DistributedApplication.CreateBuilder(args);
-
-var openai = builder.ExecutionContext.IsPublishMode
-    ? builder.AddAzureOpenAI("openai")
-    : builder.AddConnectionString("openai");
-
-builder.AddProject<Projects.ExampleProject>()
-       .WithReference(openai);
-
-// After adding all resources, run the app...
-```
-
-[!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under User Secrets, under the `ConnectionStrings` section:
-
-```json
-{
-  "ConnectionStrings": {
-    "openai": "https://{account_name}.openai.azure.com/"
-  }
-}
-```
-
-For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
+> [!NOTE]
+> Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ## Client integration
 

docs/azureai/azureai-search-document-integration.md

@@ -103,34 +103,8 @@ builder.AddProject<Projects.ExampleProject>()
 
 For more information on treating Azure AI Search resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources).
 
-Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the app host. Which is a weakly-typed approach that's based solely on a `string` value. To add a connection to an existing Azure AI Search service, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString%2A> method:
-
-```csharp
-var builder = DistributedApplication.CreateBuilder(args);
-
-var search = builder.ExecutionContext.IsPublishMode
-    ? builder.AddAzureSearch("search")
-    : builder.AddConnectionString("search");
-
-builder.AddProject<Projects.ExampleProject>()
-       .WithReference(search);
-
-// After adding all resources, run the app...
-```
-
-[!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under User Secrets, under the `ConnectionStrings` section:
-
-```json
-{
-  "ConnectionStrings": {
-    "search": "https://{account_name}.search.azure.com/"
-  }
-}
-```
-
-For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
+> [!NOTE]
+> Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Hosting integration health checks
 

docs/caching/includes/azure-redis-app-host.md

@@ -75,32 +75,27 @@ There are many more configuration options available to customize the Azure Cache
 
 ### Connect to an existing Azure Cache for Redis
 
-You might have an existing Azure Cache for Redis that you want to connect to. Instead of representing a new Azure Cache for Redis resource, you can add a connection string to the app host. To add a connection to an existing Azure Cache for Redis, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
+You might have an existing Azure Cache for Redis resource that you want to connect to. You can chain a call to annotate that your <xref:Aspire.Hosting.Azure.AzureRedisCacheResource> is an existing resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var cache = builder.AddConnectionString("azure-redis");
+var existingRedisName = builder.AddParameter("existingRedisName");
+var existingRedisResourceGroup = builder.AddParameter("existingRedisResourceGroup");
 
-builder.AddProject<Projects.WebApplication>("web")
+var cache = builder.AddAzureRedis("azcache")
+                   .AsExisting(existingRedisName, existingRedisResourceGroup);
+
+builder.AddProject<Projects.ExampleProject>()
        .WithReference(cache);
 
 // After adding all resources, run the app...
 ```
 
-[!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
-
-```json
-{
-    "ConnectionStrings": {
-        "azure-redis": "<your-redis-name>.redis.cache.windows.net:6380,ssl=true,abortConnect=False"
-    }
-}
-```
+For more information on treating Azure Cache for Redis resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources).
 
-The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"azure-redis"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
+> [!NOTE]
+> Alternatively, instead of representing an Azure Cache for Redis resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Run Azure Cache for Redis resource as a container
 

docs/database/includes/azure-sql-hosting.md

@@ -45,32 +45,28 @@ The preceding call to `AddAzureSqlServer` configures the Azure SQL server resour
 
 ### Connect to an existing Azure SQL server
 
-You might have an existing Azure SQL database that you want to connect to. Instead of representing a new Azure SQL server resource, you can add a connection string to the app host. To add a connection to an existing Azure SQL server, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
+You might have an existing Azure SQL Database service that you want to connect to. You can chain a call to annotate that your <xref:Aspire.Hosting.Azure.AzureSqlServerResource> is an existing resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var azureSql = builder.AddConnectionString("database");
+var existingSqlServerName = builder.AddParameter("existingSqlServerName");
+var existingSqlServerResourceGroup = builder.AddParameter("existingSqlServerResourceGroup");
 
-builder.AddProject<Projects.WebApplication>("web")
-       .WithReference(azureSql);
+var sqlserver = builder.AddAzureSqlServer("sqlserver")
+                       .AsExisting(existingSqlServerName, existingSqlServerResourceGroup)
+                       .AddDatabase("database");
+
+builder.AddProject<Projects.ExampleProject>()
+       .WithReference(sqlserver);
 
 // After adding all resources, run the app...
 ```
 
-[!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
-
-```json
-{
-    "ConnectionStrings": {
-        "database": "Server=tcp:<Azure-SQL-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID=<username>;"
-    }
-}
-```
+For more information on treating Azure SQL Database resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources).
 
-The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"database"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
+> [!NOTE]
+> Alternatively, instead of representing an Azure SQL Database resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Run Azure SQL server resource as a container
 

docs/database/includes/cosmos-app-host.md

@@ -76,32 +76,27 @@ There are many more configuration options available to customize the Azure Cosmo
 
 ### Connect to an existing Azure Cosmos DB account
 
-You might have an existing Azure Cosmos DB account that you want to connect to. Instead of representing a new Azure Cosmos DB resource, you can add a connection string to the app host. To add a connection to an existing Azure Cosmos DB account, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
+You might have an existing Azure Cosmos DB account that you want to connect to. You can chain a call to annotate that your <xref:Aspire.Hosting.AzureCosmosDBResource> is an existing resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var cosmos = builder.AddConnectionString("cosmos-db");
+var existingCosmosName = builder.AddParameter("existingCosmosName");
+var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");
+
+var cosmos = builder.AddAzureCosmosDB("cosmos-db")
+                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);
 
 builder.AddProject<Projects.WebApplication>("web")
        .WithReference(cosmos);
 
 // After adding all resources, run the app...
 ```
 
-[!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
-
-```json
-{
-    "ConnectionStrings": {
-        "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
-    }
-}
-```
+For more information on treating Azure Cosmos DB resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources).
 
-The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"cosmos-db"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
+> [!NOTE]
+> Alternatively, instead of representing an Azure Cosmos DB resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Add Azure Cosmos DB database and container resources
 

docs/database/includes/postgresql-flexible-server.md

@@ -88,32 +88,27 @@ There are many more configuration options available to customize the PostgreSQL
 
 ### Connect to an existing Azure PostgreSQL flexible server
 
-You might have an existing Azure PostgreSQL flexible server that you want to connect to. Instead of representing a new Azure PostgreSQL flexible server resource, you can add a connection string to the app host. To add a connection to an existing Azure PostgreSQL flexible server, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
+You might have an existing Azure PostgreSQL flexible server that you want to connect to. Chain a call to annotate that your <xref:Aspire.Hosting.Azure.AzurePostgresFlexibleServerResource> is an existing resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var postgres = builder.AddConnectionString("postgres");
+var existingPostgresName = builder.AddParameter("existingPostgresName");
+var existingPostgresResourceGroup = builder.AddParameter("existingPostgresResourceGroup");
 
-builder.AddProject<Projects.WebApplication>("web")
+var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
+                      .AsExisting(existingPostgresName, existingPostgresResourceGroup);
+
+builder.AddProject<Projects.ExampleProject>()
        .WithReference(postgres);
 
 // After adding all resources, run the app...
 ```
 
-[!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
-
-```json
-{
-    "ConnectionStrings": {
-        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
-    }
-}
-```
+For more information on treating Azure PostgreSQL flexible server resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources).
 
-The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"postgres"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
+> [!NOTE]
+> Alternatively, instead of representing an Azure PostgreSQL flexible server resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Run Azure PostgreSQL resource as a container
 

docs/messaging/azure-event-hubs-integration.md

@@ -91,32 +91,27 @@ There are many more configuration options available to customize the Event Hubs
 
 ### Connect to an existing Azure Event Hubs namespace
 
-You might have an existing Azure Event Hubs namespace that you want to connect to. Instead of representing a new Azure Event Hubs resource, you can add a connection string to the app host. To add a connection to an existing Azure Event Hubs namespace, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
+You might have an existing Azure Event Hubs service that you want to connect to. You can chain a call to annotate that your <xref:Aspire.Hosting.Azure.AzureEventHubsResource> is an existing resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var eventHubs = builder.AddConnectionString("event-hubs");
+var existingEventHubsName = builder.AddParameter("existingEventHubsName");
+var existingEventHubsResourceGroup = builder.AddParameter("existingEventHubsResourceGroup");
 
-builder.AddProject<Projects.WebApplication>("web")
+var eventHubs = builder.AddAzureEventHubs("event-hubs")
+                    .AsExisting(existingEventHubsName, existingEventHubsResourceGroup);
+
+builder.AddProject<Projects.ExampleProject>()
        .WithReference(eventHubs);
 
 // After adding all resources, run the app...
 ```
 
-[!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)]
-
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
-
-```json
-{
-  "ConnectionStrings": {
-    "event-hubs": "{your_namespace}.servicebus.windows.net"
-  }
-}
-```
+For more information on treating Azure Event Hubs resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources).
 
-The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"event-hubs"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
+> [!NOTE]
+> Alternatively, instead of representing an Azure Event Hubs resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
 
 ### Add Event Hub consumer group