Usando um Projeto de Migrações Separadas

Você pode armazenar migrações em um projeto diferente do que contém sua DbContext. Isso é recomendado quando o projeto de aplicativo é específico da plataforma, como WinUI, .NET MAUI, Blazor WebAssembly ou Azure Functions ou quando ele tem como destino um RID (identificador de runtime) específico. Ele também pode ser usado para manter mais de um conjunto de migrações.

Tip

Você pode exibir o sample deste artigo em GitHub.

Layout do projeto

O exemplo usa três projetos:

Projeto	Responsabilidade	References
`WebApplication1.Data`	Possui os `DbContext` tipos de entidade e	Provedor EF Core
`WebApplication1.Migrations`	Possui migrações, o instantâneo do modelo e a criação de contexto de tempo de design	Projeto de dados, provedor EF Core e `Microsoft.EntityFrameworkCore.Design`
`WebApplication1`	Executa o aplicativo	Projeto de dados e projeto de migrações

O aplicativo precisa de uma referência ao projeto de migrações quando descobre ou aplica migrações em tempo de execução, por exemplo, chamando Migrate. Se as migrações forem aplicadas somente por um artefato de implantação e o aplicativo nunca carregá-las, essa referência não será necessária.

Configurar os projetos

Crie uma biblioteca de classes para as migrações e adicione uma referência ao projeto que contém o DbContext.

Adicione o provedor de banco de dados e Microsoft.EntityFrameworkCore.Design o projeto de migrações. Marque o pacote de design como uma dependência de desenvolvimento privado:

<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="...">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="..." />
</ItemGroup>

<ItemGroup>
  <ProjectReference Include="..\WebApplication1.Data\WebApplication1.Data.csproj" />
</ItemGroup>

Implementar IDesignTimeDbContextFactory<TContext> no projeto de migrações. A fábrica permite que as ferramentas criem o contexto sem executar o projeto de aplicativo:

public class ApplicationDbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext>
{
    public ApplicationDbContext CreateDbContext(string[] args)
    {
        var connectionString = args.FirstOrDefault()
            ?? @"Server=(localdb)\mssqllocaldb;Database=WebApplication1;Trusted_Connection=True";

        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
            .UseSqlServer(
                connectionString,
                sqlServer => sqlServer.MigrationsAssembly(typeof(ApplicationDbContextFactory).Assembly.GetName().Name))
            .Options;

        return new ApplicationDbContext(options);
    }
}

Mantenha a configuração de modelo e provedor de tempo de design consistente com a configuração de runtime. O exemplo aceita um argumento cadeia de conexão opcional e usa uma conexão de desenvolvimento local quando nenhum argumento é fornecido.

Configure o assembly de migrações ao registrar o contexto em tempo de execução:

services.AddDbContext<ApplicationDbContext>(
    options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection"),
            x => x.MigrationsAssembly("WebApplication1.Migrations")));

Se o aplicativo aplica migrações ou as descobre em tempo de execução, adicione uma referência normal do aplicativo ao projeto de migrações:
```
<ItemGroup>
  <ProjectReference Include="..\WebApplication1.Migrations\WebApplication1.Migrations.csproj" />
</ItemGroup>
```
O projeto de dados não deve fazer referência ao projeto de migrações. Isso criaria uma dependência circular porque o projeto de migrações já faz referência ao projeto de dados.
Se as migrações já existirem, mova todos os arquivos de migração e o instantâneo do modelo para o projeto de migrações e atualize seus namespaces. Quando não há migrações existentes, a fábrica de tempo de design permite que a migração inicial seja criada diretamente no projeto de migrações.

Usar as ferramentas

Use o projeto de migrações como o projeto de destino e o projeto de inicialização. O projeto de destino recebe arquivos gerados, enquanto o projeto de inicialização é criado e executado pelas ferramentas. Nesse layout, usar o projeto de migrações para ambas impede que as ferramentas executem o código de inicialização do aplicativo.

CLI do .NET
Visual Studio

Execute estes comandos no diretório da solução:

dotnet ef migrations add NewMigration \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

As mesmas opções de projeto se aplicam a outros comandos:

dotnet ef migrations list \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

dotnet ef migrations script --output artifacts/migrations.sql \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

dotnet ef migrations bundle --output artifacts/efbundle \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

A partir do EF Core 11, as opções de projeto repetidas podem ser armazenadas em .config/dotnet-ef.json.

Use as migrações project para ambos -Project e-StartupProject:

Add-Migration NewMigration `
    -Project WebApplication1.Migrations `
    -StartupProject WebApplication1.Migrations

Os mesmos parâmetros podem ser passados para Get-Migration, Script-Migratione Bundle-Migrationos outros comandos Gerenciador de Pacotes Console.

Crie o projeto de migrações antes de executar comandos com --no-buildou antes que outro processo consuma sua saída. Um comando normal dotnet ef cria os projetos de destino e inicialização automaticamente.

Aplicativos específicos da plataforma

Não use um projeto de aplicativo específico da plataforma como o projeto de inicialização para ferramentas EF. Projetos móveis, navegador, desktop, função e projetos específicos do RID podem exigir uma carga de trabalho ou host nativo que dotnet ef não pode ser executado. A partir do EF Core 11, as ferramentas avisam quando um projeto de inicialização específico da plataforma é usado.

Use o layout descrito acima para .NET MAUI, WinUI, Blazor WebAssembly, Azure Functions e aplicativos semelhantes:

Coloque os tipos de contexto e entidade em um projeto de dados compartilhado.
Coloque as migrações e IDesignTimeDbContextFactory<TContext> em um projeto de .NET multiplataforma normal.
Execute as ferramentas com o projeto de migrações como o projeto de destino e inicialização.
Faça referência ao projeto de migrações do aplicativo somente se o aplicativo carregar ou aplicar migrações em tempo de execução.

O suporte a ferramentas diretas para projetos de plataforma Xamarin e MAUI não está planejado; consulte dotnet/efcore#7152. Xamarin aplicativos devem primeiro ser atualizados para .NET MAUI.

Arquitetura de processo

O processo que executa as ferramentas deve ser capaz de carregar cada assembly de tempo de design. Um processo de Visual Studio ou .NET de 64 bits não pode carregar um assembly de inicialização somente x86 e a mesma restrição se aplica ao Arm64 e a outras arquiteturas. Prefira um projeto de migrações anycpu. Se as dependências de tempo de design exigirem uma arquitetura específica, invoque um SDK de .NET correspondente explicitamente.

A arquitetura do processo de tempo de design é separada do destino de implantação. Ao criar um pacote, use --target-runtime ou -TargetRuntime gere um artefato para o RID de implantação, como linux-arm64 ou osx-arm64.

Comentários

Esta página foi útil?

Last updated on 2026-08-13