Document null connection string guard for PublishAsMigrationBundle with Azure Postgres

[Copilot]

Description

PublishAsMigrationBundle fails during aspire publish when the DbContext uses EnrichAzureNpgsqlDbContext, with Format of the initialization string does not conform to specification starting at index 0.

The *-generate-migration-bundle step runs dotnet ef migrations bundle, which creates the DbContext at design time to discover the model. The EF tool resource inherits the project's WithReference(<db>) wiring, so ConnectionStrings__<db> is set to a publish-time placeholder expression. EnrichAzureNpgsqlDbContext configures an Entra ID data source that parses that string eagerly during context creation, and NpgsqlConnectionStringBuilder throws. The bundle never needs a real connection string at design time — it receives one at run time via the --connection argument Aspire injects — so the fix lives in user code: guard connection-string-dependent configuration by checking whether the connection string is null.

These are documentation-only changes (no product code change required, since the bundle is configured correctly at run time).

• README.md: adds a "Troubleshooting: design-time connection strings" subsection under Publishing Support with an inline null-check example, replaces the "Additional documentation" placeholder link with the published EF migrations page (https://aspire.dev/integrations/databases/efcore/migrations/#automated-ef-migrations-with-addefmigrations), and removes the generic https://learn.microsoft.com/dotnet/aspire/ link.

Recommended user-side fix:

var connectionString = builder.Configuration.GetConnectionString("postgresdb");

builder.Services.AddPooledDbContextFactory<AppDbContext>((sp, options) =>
{
    if (connectionString is null)
        options.UseNpgsql(o => { });         // build the model without parsing a connection string
    else
        options.UseNpgsql(connectionString);
});

if (connectionString is not null)
    builder.EnrichAzureNpgsqlDbContext<AppDbContext>();

The same pattern applies to any provider that parses the connection string while the DbContext is being created.

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[Copilot]

Pull request overview

Adds troubleshooting guidance to the EntityFrameworkCore hosting integration documentation to address PublishAsMigrationBundle failures when EF Core design-time tooling instantiates a DbContext while only a publish-time placeholder connection string is available.

Changes:

• Documented why design-time DbContext creation during migration bundle generation can fail when providers eagerly parse connection strings (example: EnrichAzureNpgsqlDbContext).
• Added a recommended EF.IsDesignTime guard pattern to avoid design-time connection-string parsing while still receiving the real connection string at runtime via --connection.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17856

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17856"

[Waleed Khaled (Waleed-KH)]

Note this solution would make the run mode fails during database update command:

[Andriy Svyryd (AndriySvyryd)]

Waleed Khaled (@Waleed-KH) Good point. Instead of EF.IsDesignTime make the condition based on whether the connection string is null.

Copilot Change the readme accordingly

[Copilot]

Waleed Khaled (@Waleed-KH) Good point. Instead of EF.IsDesignTime make the condition based on whether the connection string is null.

Copilot Change the readme accordingly

Updated in the latest commit. The example now reads the connection string once up front and gates both UseNpgsql and EnrichAzureNpgsqlDbContext on connectionString is null / connectionString is not null.

[Waleed Khaled (Waleed-KH)]

Andriy Svyryd (@AndriySvyryd) Now the publish is failing again 🤣. After doing further checks, I discovered that the migration bundle can be generated without any problems even when the connectionString is set to null. The issue occur because, during publish, Aspire provides a connection string that the DbContext cannot resolve.

To fix this, I believe it would be better if Aspire do not pass any connection string when running the generate migration bundle command during publish, allowing it to function correctly without requiring any checks from the user-side.

[Andriy Svyryd (AndriySvyryd)]

I see, #17905 should take care of that