From 155ee31430e193e59eaba34c976b9be003e1241c Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 07:58:46 +0000 Subject: [PATCH] docs: document PublishAsConnectionString obsolete, update examples to use AddConnectionString - Update 'Parameter example' in external-parameters.mdx to use execution-context-based pattern (IsRunMode) instead of the now-obsolete PublishAsConnectionString() API - Update the Japanese localized version of external-parameters.mdx to match - Mark PublishAsConnectionString as obsolete in the azure/overview.mdx API table and add a migration caution callout showing the AddConnectionString pattern with execution context Relates to microsoft/aspire#18044 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/fundamentals/external-parameters.mdx | 27 ++++++++++--------- .../integrations/cloud/azure/overview.mdx | 13 ++++++++- .../ja/fundamentals/external-parameters.mdx | 19 ++++++------- 3 files changed, 37 insertions(+), 22 deletions(-) diff --git a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx index 98eae1133..b541a09ac 100644 --- a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx +++ b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx @@ -619,9 +619,11 @@ To express a parameter, consider the following example code: ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var db = builder.AddSqlServer("sql") - .PublishAsConnectionString() - .AddDatabase("db"); +// In run mode, add the actual SQL Server resource. +// In publish mode, use a connection string representing an external SQL Server instance. +IResourceBuilder db = builder.ExecutionContext.IsRunMode + ? builder.AddSqlServer("sql").AddDatabase("db") + : builder.AddConnectionString("db"); var insertionRows = builder.AddParameter("insertionRows"); @@ -640,9 +642,11 @@ import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); -const sql = await builder.addSqlServer('sql'); -await sql.publishAsConnectionString(); -const db = await sql.addDatabase('db'); +// In run mode, add the actual SQL Server resource. +// In publish mode, use a connection string representing an external SQL Server instance. +const db = builder.executionContext.isRunMode + ? await builder.addSqlServer('sql').then(sql => sql.addDatabase('db')) + : await builder.addConnectionString('db'); const insertionRows = await builder.addParameter('insertionRows'); @@ -663,12 +667,11 @@ The following steps are performed: -1. Adds a SQL Server resource named `sql` and publishes it as a connection string. -2. Adds a database named `db`. -3. Adds a parameter named `insertionRows`. -4. Adds a project named `api` and associates it with the `Projects.Parameters_ApiService` project resource type-parameter. -5. Passes the `insertionRows` parameter to the `api` project. -6. References the `db` database. +1. In run mode, adds a SQL Server resource named `sql` and a database named `db`. In publish mode, uses an external connection string named `db`. +2. Adds a parameter named `insertionRows`. +3. Adds a project named `api` and associates it with the `Projects.Parameters_ApiService` project resource type-parameter. +4. Passes the `insertionRows` parameter to the `api` project. +5. References the `db` database. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx index 407b62b8d..22e7ac503 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx @@ -118,13 +118,24 @@ The following table summarizes the naming conventions used to express Azure reso | Operation | API | Description | |--|--|--| -| Publish | `PublishAsConnectionString` | Changes the resource to be published as a connection string reference in the manifest. | +| Publish | `PublishAsConnectionString` _(obsolete)_ | Changes the resource to be published as a connection string reference in the manifest. Use `AddConnectionString` with the [execution context](/get-started/app-host/) instead. | | Publish | `PublishAsExisting` | Uses an existing Azure resource when the application is deployed instead of creating a new one. | | Run | `RunAsContainer` | Configures an equivalent container to run locally. For more information, see [Local containers](#local-containers). | | Run | `RunAsEmulator` | Configures the Azure resource to be emulated. For more information, see [Local emulators](#local-emulators). | | Run | `RunAsExisting` | Uses an existing resource when the application is running instead of creating a new one. | | Publish and Run | `AsExisting` | Uses an existing resource regardless of the operation. | +:::caution[PublishAsConnectionString is obsolete] +`PublishAsConnectionString` is obsolete as of .NET Aspire 9.5. It only changes the manifest representation and has no effect on other publishers. To express different run and publish behavior, use [`AddConnectionString`](/fundamentals/external-parameters/#connection-string-values) with the execution context: + +```csharp +var resource = builder.ExecutionContext.IsPublishMode + ? builder.AddAzureServiceBus("messaging") + : builder.AddConnectionString("messaging"); +``` + +::: + diff --git a/src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx b/src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx index 9e4bf01b4..1535a3baa 100644 --- a/src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx +++ b/src/frontend/src/content/docs/ja/fundamentals/external-parameters.mdx @@ -517,9 +517,11 @@ builder.AddProject("customerapi ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var db = builder.AddSqlServer("sql") - .PublishAsConnectionString() - .AddDatabase("db"); +// 実行モードでは実際の SQL Server リソースを追加します。 +// 発行モードでは外部 SQL Server インスタンスを表す接続文字列を使用します。 +IResourceBuilder db = builder.ExecutionContext.IsRunMode + ? builder.AddSqlServer("sql").AddDatabase("db") + : builder.AddConnectionString("db"); var insertionRows = builder.AddParameter("insertionRows"); @@ -557,12 +559,11 @@ await builder.build().run(); -1. `sql` という名前の SQL Server リソースを追加し、接続文字列として公開します。 -2. `db` という名前のデータベースを追加します。 -3. `insertionRows` という名前のパラメーターを追加します。 -4. `api` という名前のプロジェクトを追加し、それを `Projects.Parameters_ApiService` のプロジェクト リソース型として関連付けます。 -5. `insertionRows` パラメーターを `api` プロジェクトに渡します。 -6. `db` データベースを参照します。 +1. 実行モードでは `sql` という名前の SQL Server リソースと `db` という名前のデータベースを追加します。発行モードでは `db` という名前の外部接続文字列を使用します。 +2. `insertionRows` という名前のパラメーターを追加します。 +3. `api` という名前のプロジェクトを追加し、それを `Projects.Parameters_ApiService` のプロジェクト リソース型として関連付けます。 +4. `insertionRows` パラメーターを `api` プロジェクトに渡します。 +5. `db` データベースを参照します。