Referência de ferramentas principais do Entity Framework - Console do Gerenciador de Pacotes no Visual Studio

Artigo
02/04/2025

As ferramentas do Console do Gestor de Pacotes (PMC) para o Entity Framework Core executam tarefas de desenvolvimento de design. Por exemplo, eles criam migrações , aplicam migrações e geram código para um modelo com base em um banco de dados existente. Os comandos são executados dentro do Visual Studio usando o Console do Gerenciador de Pacotes . Essas ferramentas funcionam com projetos .NET Framework e .NET Core.

Se não estiver a usar o Visual Studio, recomendamos as Ferramentas de Linha de Comando do EF Core como alternativa. As ferramentas da CLI do .NET Core são multiplataforma e executadas dentro de um prompt de comando.

Advertência

Este artigo usa um banco de dados local que não exige que o usuário seja autenticado. Os aplicativos de produção devem usar o fluxo de autenticação mais seguro disponível. Para obter mais informações sobre autenticação para aplicativos de teste e produção implantados, consulte Fluxos de autenticação seguros.

Instale as ferramentas

Instale as ferramentas do Console do Gerenciador de Pacotes executando o seguinte comando no Console do Gerenciador de Pacotes :

Install-Package Microsoft.EntityFrameworkCore.Tools

Atualize as ferramentas executando o seguinte comando no Console do Gerenciador de Pacotes .

Update-Package Microsoft.EntityFrameworkCore.Tools

Verifique a instalação

Verifique se as ferramentas estão instaladas executando este comando:

Get-Help about_EntityFrameworkCore

A saída tem esta aparência (não informa qual versão das ferramentas você está usando):


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

TOPIC
    about_EntityFrameworkCore

SHORT DESCRIPTION
    Provides information about the Entity Framework Core Package Manager Console Tools.

<A list of available commands follows, omitted here.>

Utilize as ferramentas

Antes de utilizar as ferramentas:

Entenda a diferença entre projeto alvo e startup.
Saiba como usar as ferramentas com bibliotecas de classes do .NET Standard.
Para ASP.NET projetos principais, defina o ambiente.

Projeto alvo e startup

Os comandos referem-se a um projeto e a um projeto startup .

O do projeto também é conhecido como o projeto de destino porque é onde os comandos adicionam ou removem arquivos. Por padrão, o projeto Padrão selecionado no Console do Gerenciador de Pacotes é o projeto de destino. Você pode especificar um projeto diferente como projeto de destino usando o parâmetro -Project.
O projeto de inicialização é aquele que as ferramentas criam e executam. As ferramentas têm que executar o código do aplicativo em tempo de design para obter informações sobre o projeto, como a cadeia de conexão do banco de dados e a configuração do modelo. Por padrão, o Projeto de Inicialização no Gerenciador de Soluções é o projeto de inicialização. Você pode especificar um projeto diferente como projeto de inicialização usando o parâmetro -StartupProject.

O projeto inicial e o projeto-alvo são muitas vezes o mesmo projeto. Um cenário típico em que são projetos separados é quando:

O contexto do EF Core e as classes de entidade estão em uma biblioteca de classes do .NET Core.
Um aplicativo de console .NET Core ou aplicativo Web faz referência à biblioteca de classes.

Também é possível colocar o código de migrações em uma biblioteca de classes separada do contexto do EF Core.

Outros quadros-alvo

As ferramentas do Console do Gerenciador de Pacotes funcionam com projetos .NET Core ou .NET Framework. Os aplicativos que têm o modelo EF Core em uma biblioteca de classes .NET Standard podem não ter um projeto .NET Core ou .NET Framework. Por exemplo, isso é verdade para aplicativos Xamarin e Plataforma Universal do Windows. Nesses casos, você pode criar um projeto de aplicativo de console .NET Core ou .NET Framework cuja única finalidade é atuar como projeto de inicialização para as ferramentas. O projeto pode ser um projeto fictício sem código real — é necessário apenas fornecer um alvo para as ferramentas.

Importante

Xamarin.Android, Xamarin.iOS, Xamarin.Mac agora estão integrados diretamente ao .NET (começando com .NET 6) como .NET para Android, .NET para iOS e .NET para macOS. Se você estiver criando com esses tipos de projeto hoje, eles devem ser atualizados para projetos no estilo SDK do .NET para suporte contínuo. Para obter mais informações sobre como atualizar projetos Xamarin para .NET, consulte a documentação Upgrade from Xamarin to .NET & .NET MAUI.

Por que é necessário um projeto fictício? Como mencionado anteriormente, as ferramentas têm que executar o código da aplicação em tempo de concepção. Para fazer isso, eles precisam usar o tempo de execução do .NET Core ou .NET Framework. Quando o modelo EF Core está em um projeto destinado ao .NET Core ou .NET Framework, as ferramentas do EF Core tomam emprestado o tempo de execução do projeto. Eles não podem fazer isso se o modelo EF Core estiver em uma biblioteca de classes .NET Standard. O .NET Standard não é uma implementação real do .NET; é uma especificação de um conjunto de APIs que as implementações .NET devem suportar. Portanto, o .NET Standard não é suficiente para que as ferramentas EF Core executem o código do aplicativo. O projeto fictício que você cria para usar como projeto de inicialização fornece uma plataforma de destino concreta na qual as ferramentas podem carregar a biblioteca de classes .NET Standard.

ASP.NET Ambiente central

Você pode especificar o ambiente para projetos ASP.NET Core na linha de comandos. Este e quaisquer argumentos adicionais são passados para Program.CreateHostBuilder.

Update-Database -Args '--environment Production'

Parâmetros comuns

A tabela a seguir mostra parâmetros que são comuns a todos os comandos do EF Core:

Parâmetro	Descrição
`-Context <String>`	A classe `DbContext` a ser usada. Nome da classe somente ou totalmente qualificado com namespaces. Se esse parâmetro for omitido, o EF Core localizará a classe de contexto. Se houver várias classes de contexto, esse parâmetro será necessário.
`-Project <String>`	O projeto-alvo. Se esse parâmetro for omitido, o projeto padrão para o Console do Gerenciador de Pacotes será usado como o projeto de destino.
`-StartupProject <String>`	O projeto startup. Se esse parâmetro for omitido, o projeto de inicialização nas propriedades da solução será usado como o projeto de destino.
`-Args <String>`	Argumentos passados para o aplicativo.
`-Verbose`	Mostrar saída detalhada.

Para mostrar informações de ajuda sobre um comando, use o comando Get-Help do PowerShell.

Dica

Os parâmetros Context, Projecte StartupProject suportam a expansão por tabulação.

Add-Migration

Adiciona uma nova migração.

Parâmetros:

Parâmetro	Descrição
`-Name <String>`	O nome da migração. Este é um parâmetro posicional e é obrigatório.
`-OutputDir <String>`	O diretório usado para saída dos arquivos. Os caminhos são relativos ao diretório do projeto de destino. O padrão é "Migrações".
`-Namespace <String>`	O namespace a ser usado para as classes geradas. Por defeito, é gerado a partir do diretório de saída.

Os parâmetros comuns estão listados acima.

Bundle-Migration

Cria um executável para atualizar o banco de dados.

Parâmetros:

Parâmetro	Descrição
`-Output <String>`	O caminho do arquivo executável a ser criado.
`-Force`	Substituir ficheiros existentes.
`-SelfContained`	Além disso, agrupe o tempo de execução do .NET para que ele não precise ser instalado na máquina.
`-TargetRuntime <String>`	O tempo de execução alvo para agrupar.
`-Framework <String>`	O quadro alvo. Por padrão, seleciona-se o primeiro no projeto.

Os parâmetros comuns estão listados acima.

Drop-Database

Descarta o banco de dados.

Parâmetros:

Parâmetro	Descrição
`-WhatIf`	Mostre qual banco de dados seria descartado, mas não o solte.

Os parâmetros comuns estão listados acima.

Get-DbContext

Lista e obtém informações sobre os tipos de DbContext disponíveis.

Os parâmetros comuns estão listados acima.

Get-Migration

Lista as migrações disponíveis.

Parâmetros:

Parâmetro	Descrição
`-Connection <String>`	A cadeia de conexão com o banco de dados. O padrão é o especificado em AddDbContext ou OnConfiguring.
`-NoConnect`	Não se conecte ao banco de dados.

Os parâmetros comuns estão listados acima.

Optimize-DbContext

Gera uma versão compilada do modelo usado pelo DbContext.

Consulte Modelos compilados para obter mais informações.

Parâmetros:

Parâmetro	Descrição
`-OutputDir <String>`	O diretório para colocar arquivos. Os caminhos são relativos ao diretório do projeto.
`-Namespace <String>`	O namespace a ser usado para todas as classes geradas. O padrão é gerado a partir do namespace raiz e do diretório de saída mais `CompiledModels`.

Os parâmetros comuns estão listados acima.

Observação

As ferramentas PMC atualmente não suportam a geração de código necessário para a compilação NativeAOT e consultas pré-compiladas.

O exemplo a seguir usa os padrões e funciona se houver apenas um DbContext no projeto:

Optimize-DbContext

O exemplo a seguir otimiza o modelo para o contexto com o nome especificado e o coloca em uma pasta e namespace separados:

Optimize-DbContext -OutputDir Models -Namespace BlogModels -Context BlogContext

Remove-Migration

Remove a última migração (reverte as alterações de código que foram feitas para a migração).

Parâmetros:

Parâmetro	Descrição
`-Force`	Reverter a migração (reverter as alterações que foram aplicadas ao banco de dados).

Os parâmetros comuns estão listados acima.

Scaffold-DbContext

Gera código para um DbContext e tipos de entidade para uma base de dados. Para que Scaffold-DbContext gere um tipo de entidade, a tabela do banco de dados deve ter uma chave primária.

Parâmetros:

Parâmetro	Descrição
`-Connection <String>`	A cadeia de conexão com o banco de dados. O valor pode ser name=<nome da cadeia de conexão>. Nesse caso, o nome vem das fontes de configuração que estão configuradas para o projeto. Este é um parâmetro posicional e é obrigatório.
`-Provider <String>`	O provedor a utilizar. Normalmente, este é o nome do pacote NuGet, por exemplo: `Microsoft.EntityFrameworkCore.SqlServer`. Este é um parâmetro posicional e é obrigatório.
`-OutputDir <String>`	O diretório no qual colocar arquivos de classe de entidade. Os caminhos são relativos ao diretório do projeto.
`-ContextDir <String>`	O diretório para colocar o arquivo `DbContext`. Os caminhos são relativos ao diretório do projeto.
`-Namespace <String>`	O namespace a ser usado para todas as classes geradas. Por defeito, é gerado a partir do namespace raiz e do diretório de saída.
`-ContextNamespace <String>`	O namespace a ser usado para a classe `DbContext` gerada. Nota: substitui `-Namespace`.
`-Context <String>`	O nome da classe `DbContext` a ser gerada.
`-Schemas <String[]>`	Os esquemas de tabelas e vistas para gerar tipos de entidade. Se esse parâmetro for omitido, todos os esquemas serão incluídos. Se essa opção for usada, todas as tabelas e exibições nos esquemas serão incluídas no modelo, mesmo que não sejam explicitamente incluídas usando -Table.
`-Tables <String[]>`	As tabelas e exibições para gerar tipos de entidade. Tabelas ou exibições em um esquema específico podem ser incluídas usando o formato 'schema.table' ou 'schema.view'. Se esse parâmetro for omitido, todas as tabelas e exibições serão incluídas.
`-DataAnnotations`	Use atributos para configurar o modelo (sempre que possível). Se esse parâmetro for omitido, somente a API fluente será usada.
`-UseDatabaseNames`	Use nomes de tabela, exibição, sequência e coluna exatamente como aparecem no banco de dados. Se esse parâmetro for omitido, os nomes de banco de dados serão alterados para estarem mais em conformidade com as convenções de estilo de nome C#.
`-Force`	Sobrescrever ficheiros existentes.
`-NoOnConfiguring`	Não gere `DbContext.OnConfiguring`.
`-NoPluralize`	Não use o pluralizador.

Os parâmetros comuns estão listados acima.

Exemplo:

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

Exemplo que faz scaffold apenas às tabelas selecionadas e cria o contexto numa pasta separada com um nome e um namespace especificados.

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models -Tables "Blog","Post" -ContextDir Context -Context BlogContext -ContextNamespace New.Namespace

O exemplo a seguir lê a cadeia de conexão usando o Configuration.

Scaffold-DbContext "Name=ConnectionStrings:Blogging" Microsoft.EntityFrameworkCore.SqlServer

Script-DbContext

Gera um script SQL a partir do DbContext. Ignora quaisquer migrações.

Parâmetros:

Parâmetro	Descrição
`-Output <String>`	O arquivo para gravar o resultado.

Os parâmetros comuns estão listados acima.

Script-Migration

Gera um script SQL que aplica todas as alterações de uma migração selecionada para outra migração selecionada.

Parâmetros:

Parâmetro	Descrição
`-From <String>`	A migração inicial. As migrações podem ser identificadas pelo nome ou pelo ID. O número 0 é um caso especial que significa antes da primeira migração. O padrão é 0.
`-To <String>`	O fim da migração. Define-se por predefinição para a última migração.
`-Idempotent`	Gere um script que pode ser usado em um banco de dados em qualquer migração.
`-NoTransactions`	Não gere instruções de transação SQL.
`-Output <String>`	O arquivo para gravar o resultado. SE esse parâmetro for omitido, o arquivo será criado com um nome gerado na mesma pasta em que os arquivos de tempo de execução do aplicativo são criados, por exemplo: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Os parâmetros comuns estão listados acima.

Dica

Os parâmetros To, Frome Output suportam a expansão por tabulação.

O exemplo a seguir cria um script para a migração InitialCreate (de um banco de dados sem migrações), usando o nome da migração.

Script-Migration 0 InitialCreate

O exemplo a seguir cria um script para todas as migrações após a migração InitialCreate, usando a ID de migração.

Script-Migration 20180904195021_InitialCreate

Update-Database

Atualiza o banco de dados para a última migração ou para uma migração especificada.

Parâmetro	Descrição
`-Migration <String>`	A migração-alvo. As migrações podem ser identificadas pelo nome ou pelo ID. O número 0 é um caso especial que significa antes da primeira migração e faz com que todas as migrações sejam revertidas. Se nenhuma migração for especificada, o comando assumirá como padrão a última migração.
`-Connection <String>`	A cadeia de conexão com o banco de dados. O padrão é o especificado em `AddDbContext` ou `OnConfiguring`.

Os parâmetros comuns estão listados acima.

Dica

O parâmetro Migration suporta expansão de tabulação.

O exemplo a seguir reverte todas as migrações.

Update-Database 0

Os exemplos a seguir atualizam o banco de dados para uma migração especificada. O primeiro usa o nome da migração e o segundo usa o ID de migração e uma conexão especificada:

Update-Database InitialCreate
Update-Database 20180904195021_InitialCreate -Connection your_connection_string

Partilhar via

Referência de ferramentas principais do Entity Framework - Console do Gerenciador de Pacotes no Visual Studio

Instale as ferramentas

Verifique a instalação

Utilize as ferramentas

Projeto alvo e startup

Outros quadros-alvo

ASP.NET Ambiente central

Parâmetros comuns

Add-Migration

Bundle-Migration

Drop-Database

Get-DbContext

Get-Migration

Optimize-DbContext

Remove-Migration

Scaffold-DbContext

Script-DbContext

Script-Migration

Update-Database

Recursos adicionais

Recursos adicionais