EFMigrationResourceBuilderExtensions Methods

PublishAsMigrationBundle(IResourceBuilder<EFMigrationResource>, string?, bool, bool, string?)extensionIResourceBuilder<EFMigrationResource>

Configures the EF migration resource to generate a migration bundle during publishing.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> PublishAsMigrationBundle(
        this IResourceBuilder<EFMigrationResource> builder,
        string? targetRuntime = null,
        bool selfContained = false,
        bool publishContainer = false,
        string? baseImage = null)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L161-L184

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

targetRuntimestring?optional The target runtime identifier for the bundle (e.g., linux-x64, win-x64). If null and publishContainer is true, defaults to linux-x64 to match the default Linux base container image used for the generated Dockerfile. If null and publishContainer is false, the bundle targets the runtime hosting aspire publish.

selfContainedbooloptional If true, creates a self-contained bundle that includes the .NET runtime.

publishContainerbooloptional If true, the bundle is published as a container image that applies migrations at deploy time. The resource becomes a compute resource; each target environment deploys it the same way it deploys any other container (supplying connection strings from referenced ApplicationModel.IResourceWithConnectionString dependencies via the standard WithReference mechanism).

baseImagestring?optional Overrides the base container image for the generated Dockerfile. When null (the default), the image is derived from the project's target framework — for example, mcr.microsoft.com/dotnet/runtime:10.0 for a net10.0 framework-dependent bundle. Set this when the default is not suitable, e.g. for preview SDKs or custom base images. Only meaningful when publishContainer is true.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

During aspire publish, the bundle executable is written to the publish output directory under the efmigrations folder. When publishContainer is true, Aspire also generates a Dockerfile that packages the bundle into a container image; the container reads the connection string from a ConnectionStrings__<name> environment variable injected automatically for a ApplicationModel.IResourceWithConnectionString that the migration resource references or waits on.

The startup project (the project on which AddEFMigrations was invoked) and the migrations project (configured via EFMigrationResourceBuilderExtensions.WithMigrationsProject or EFMigrationResourceBuilderExtensions.WithMigrationsProject, if different) must both list the target runtime in their <RuntimeIdentifiers> MSBuild property. If publishContainer = true, by default this means adding at minimum <RuntimeIdentifiers>linux-x64</RuntimeIdentifiers> to both projects.

PublishAsMigrationScript(IResourceBuilder<EFMigrationResource>, bool, bool)extensionIResourceBuilder<EFMigrationResource>

Configures the EF migration resource to generate a migration script during publishing.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> PublishAsMigrationScript(
        this IResourceBuilder<EFMigrationResource> builder,
        bool idempotent = true,
        bool noTransactions = false)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L103-L106

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

idempotentbooloptional If true (the default), generates an idempotent script with IF NOT EXISTS checks so it can be safely re-run against a database that has already had some or all of the migrations applied.

noTransactionsbooloptionalIf true, omits transaction statements from the script.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

During aspire publish, the generated SQL script is written to the publish output directory under the efmigrations folder. The script is included as a deployment artifact, but it is not executed automatically during deployment.

RunDatabaseUpdateOnStart(IResourceBuilder<EFMigrationResource>)extensionIResourceBuilder<EFMigrationResource>

Configures the EF migration resource to run database update when the AppHost starts.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> RunDatabaseUpdateOnStart(
        this IResourceBuilder<EFMigrationResource> builder)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L38-L46

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

When enabled, migrations are applied during AppHost startup. This only affects local run-mode execution. The migrations resource is not deployed with the app, so this method has no effect during publish or deployment.

A health check is automatically registered for this resource, allowing other resources to use .WaitFor() to wait until migrations complete before starting.

WithMigrationNamespace(IResourceBuilder<EFMigrationResource>, string)extensionIResourceBuilder<EFMigrationResource>

Configures the namespace for new migrations created with the Add Migration command.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> WithMigrationNamespace(
        this IResourceBuilder<EFMigrationResource> builder,
        string @namespace)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L218-L220

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

namespacestringThe namespace for generated migrations.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

If not specified, the namespace will be derived from the project's default namespace. Example: MyApp.Data.Migrations or MyApp.Infrastructure.Migrations.

WithMigrationOutputDirectory(IResourceBuilder<EFMigrationResource>, string)extensionIResourceBuilder<EFMigrationResource>

Configures the output directory for new migrations created with the Add Migration command.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> WithMigrationOutputDirectory(
        this IResourceBuilder<EFMigrationResource> builder,
        string outputDirectory)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L200-L202

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

outputDirectorystringThe output directory path relative to the project root.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

If not specified, migrations will be placed in the default Migrations directory. Example: Data/Migrations or Infrastructure/Migrations.

WithMigrationsProject(IResourceBuilder<EFMigrationResource>, string)extensionIResourceBuilder<EFMigrationResource>

Configures a separate project containing the migrations using a project path.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> WithMigrationsProject(
        this IResourceBuilder<EFMigrationResource> builder,
        string projectPath)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L240-L244

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

projectPathstringThe path to the project file containing the migrations.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

Use this method when the migrations are in a different project than the startup project. The target project's path will be used for migration operations while the startup project remains the original project. The project resource on which AddEFMigrations is invoked should be the startup project (the project that contains the DbContext configuration).

WithMigrationsProject(IResourceBuilder<EFMigrationResource>)extensionIResourceBuilder<EFMigrationResource>

Configures a separate project containing the migrations using a project metadata type.

public static class EFMigrationResourceBuilderExtensions
{
    public static IResourceBuilder<EFMigrationResource> WithMigrationsProject<TProject>(
        this IResourceBuilder<EFMigrationResource> builder)
    {
        // ...
    }
}

EFMigrationResourceBuilderExtensions.cs#L265-L266

Parameters

builderIResourceBuilder<EFMigrationResource>The resource builder.

Returns

IResourceBuilder<EFMigrationResource>The resource builder for chaining.

Remarks

Use this method when the migrations are in a different project than the startup project. The target project's path will be used for migration operations while the startup project remains the original project. The project resource on which AddEFMigrations is invoked should be the startup project (the project that contains the DbContext configuration).