Referência de ferramentas do Entity Framework Core – Console do gerenciador de pacotes no Visual Studio

As ferramentas do PMC (Console do gerenciador de pacotes) para o Entity Framework Core executam tarefas de desenvolvimento em tempo de design. Por exemplo, eles criam migrações, aplicam migrações e geram o 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.

Se você não estiver usando o Visual Studio, é recomendável usar as Ferramentas de linha de comando do EF Core. As ferramentas da CLI do .NET são multiplataforma e são executadas dentro de um prompt de comando.

Warning

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.

Instalar 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 comando a seguir no Console do gerenciador de pacotes.

Update-Package Microsoft.EntityFrameworkCore.Tools

Verificar a instalação

Execute este comando para verificar se as ferramentas estão instaladas:

Get-Help about_EntityFrameworkCore

A saída é semelhante a esta aqui (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.>

Usar as ferramentas

Antes de usar as ferramentas:

• Entenda a diferença entre o projeto de destino e de inicialização.
• Saiba como usar as ferramentas com bibliotecas de classes do .NET Standard.
• Em projetos do ASP.NET Core, defina o ambiente.

Projeto de destino e de inicialização

Os comandos referem-se a um projeto e a um projeto de inicialização.

• O projeto também é conhecido como projeto de destino porque é em que os comandos adicionam ou removem arquivos. Por padrão, o projeto de destino é o projeto padrão selecionado no console do gerenciador de pacotes. É possível especificar outro projeto 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 de executar o código do aplicativo no momento do design para obter informações sobre o projeto, como a cadeia de conexões de banco de dados e a configuração do modelo. Por padrão, o projeto de inicialização é aquele presente no Gerenciador de Soluções. É possível especificar outro projeto como projeto de inicialização usando o parâmetro -StartupProject.

O projeto de inicialização e o projeto de destino geralmente são o mesmo projeto. Um típico cenário em que eles são projetos separados é quando:

• As classes de contexto e entidade do EF Core estão em uma biblioteca de classes do .NET.
• Um aplicativo de console do .NET 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 Entity Framework Core.

Outras estruturas de destino

As ferramentas do Console do Gerenciador de Pacotes funcionam com projetos .NET ou .NET Framework. Os aplicativos que têm o modelo EF Core em uma biblioteca de classes do .NET Standard podem não ter um projeto .NET ou .NET Framework. Por exemplo, isso se aplica aos aplicativos o Xamarin e a Plataforma Universal do Windows. Nesses casos, você pode criar um projeto de aplicativo de console .NET 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; ele só é necessário para fornecer um destino para as ferramentas.

Important

Xamarin.Android, Xamarin.iOS, Xamarin.Mac agora estão integrados diretamente ao .NET (começando com o .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 mais informações sobre como atualizar projetos do Xamarin para o .NET, consulte a documentação Atualização do Xamarin para .NET & .NET MAUI.

Por que um projeto fictício é obrigatório? Conforme mencionado anteriormente, as ferramentas devem executar o código do aplicativo em tempo de design. Para fazer isso, eles precisam usar o runtime do .NET ou do .NET Framework. Quando o modelo do EF Core está em um projeto direcionado ao .NET ou ao .NET Framework, as ferramentas do EF Core emprestam o runtime do projeto. Elas não podem fazer isso se o modelo do Entity Framework Core estiver em uma biblioteca de classes do .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 do .NET devem dar suporte. Portanto, o .NET Standard não é suficiente para que as ferramentas do Entity Framework Core executem o código do aplicativo. O projeto fictício que você criar para utilizar como projeto de inicialização fornece uma plataforma de destino concreta na qual as ferramentas podem carregar a biblioteca de classes .NET Standard.

Ambiente do ASP.NET Core

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

Update-Database -Args '--environment Production'

Common parameters

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

Parameter	Description
-Context <String>	A classe DbContext a ser usada. Somente nome de classe ou totalmente qualificado com namespaces. Se esse parâmetro for omitido, o EF Core encontrará a classe de contexto. Se houver várias classes de contexto, esse parâmetro será necessário.
-Project <String>	O projeto de destino. Se esse parâmetro for omitido, o projeto padrão do Console do gerenciador de pacotes será usado como o projeto de destino.
-StartupProject <String>	O projeto de inicialização. 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 a saída detalhada.

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

Tip

Os parâmetros Context, Project e StartupProject dão suporte à expansão de tabulação.

Add-Migration

Adiciona uma nova migração.

Parameters:

Parameter	Description
-Name <String>	O nome da migração. Esse parâmetro é posicional e obrigatório.
-OutputDir <String>	O diretório utilizado para a 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 que será utilizado para as classes geradas. O padrão é 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.

Parameters:

Parameter	Description
-Output <String>	O caminho do arquivo executável que será criado.
-Force	Substitui os arquivos existentes.
-SelfContained	Também agrupa o runtime do .NET para que ele não precise ser instalado no computador.
-TargetRuntime <String>	O runtime de destino para o qual o pacote deve ser feito.
-Framework <String>	A estrutura de destino. O padrão é o primeiro do projeto.

Os parâmetros comuns estão listados acima.

Drop-Database

Remove o banco de dados.

Parameters:

Parameter	Description
-WhatIf	Mostre qual banco de dados seria removido, mas não o remova.

Os parâmetros comuns estão listados acima.

Get-DbContext

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

Os parâmetros comuns estão listados acima.

Get-Migration

Lista as migrações disponíveis.

Parameters:

Parameter	Description
-Connection <String>	A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou OnConfiguring.
-NoConnect	Não se conectar ao banco de dados.

Os parâmetros comuns estão listados acima.

Optimize-DbContext

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

Consulte Modelos compilados para obter mais informações.

Parameters:

Parameter	Description
-OutputDir <String>	O diretório em que os arquivos serão colocados. Os caminhos são relativos ao diretório do projeto.
-Namespace <String>	O namespace que será utilizado em 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.

Note

No momento, as ferramentas PMC não dão suporte à geração de código necessário para 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 migração mais recente (reverte as alterações de código que foram feitas para a migração).

Parameters:

Parameter	Description
-Force	Reverte a migração (reverte as alterações que foram aplicadas ao banco de dados).

Os parâmetros comuns estão listados acima.

Scaffold-DbContext

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

Parameters:

Parameter	Description
-Connection <String>	A cadeia de conexão para o banco de dados. O valor pode ser name=<name da cadeia de conexão>. Nesse caso, o nome vem das fontes de configuração que estão configuradas para o projeto. Esse parâmetro é posicional e obrigatório.
-Provider <String>	O provedor a ser usado. Normalmente, esse é o nome do pacote NuGet, por exemplo: Microsoft.EntityFrameworkCore.SqlServer. Esse parâmetro é posicional e obrigatório.
-OutputDir <String>	O diretório para colocar os arquivos de classe da entidade. Os caminhos são relativos ao diretório do projeto.
-ContextDir <String>	O diretório no qual colocar o arquivo DbContext. Os caminhos são relativos ao diretório do projeto.
-Namespace <String>	O namespace que será utilizado em todas as classes geradas. O padrão é gerado a partir do namespace raiz e do diretório de saída.
-ContextNamespace <String>	O namespace que será utilizado para a classe DbContext gerada. Observação: substitui -Namespace.
-Context <String>	O nome da classe DbContext que será gerada.
-Schemas <String[]>	Os esquemas de tabelas e exibições para os quais gerar tipos de entidades. Se esse parâmetro for omitido, todos os esquemas serão incluídos. Se essa opção for utilizada, todas as tabelas e exibições nos esquemas serão incluídas no modelo, mesmo que não tenham sido explicitamente incluídas com o uso de -Table.
-Tables <String[]>	As tabelas e exibições para as quais gerar tipos de entidades. 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	Usar atributos para configurar o modelo (sempre que possível). Se esse parâmetro for omitido, somente a API fluente será usada.
-UseDatabaseNames	Usar nomes de tabelas, exibições, sequências e colunas exatamente como aparecem no banco de dados. Se esse parâmetro for omitido, os nomes de banco de dados serão alterados para corresponder melhor às convenções de estilo de nome de C#.
-Force	Substitui os arquivos existentes.
-NoOnConfiguring	Não gere DbContext.OnConfiguring.
-NoPluralize	Não utilize o pluralizador.

Os parâmetros comuns estão listados acima.

Example:

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

Exemplo que faz scaffolding apenas de tabelas selecionadas e cria o contexto em uma pasta separada com um nome e 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 Configuração.

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

Script-DbContext

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

Parameters:

Parameter	Description
-Output <String>	O arquivo no qual 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 em outra migração selecionada.

Parameters:

Parameter	Description
-From <String>	A migração inicial. As migrações podem ser identificadas por nome ou por ID. O número 0 é um caso especial que significa antes da primeira migração. Assume o padrão de 0.
-To <String>	A migração final. O padrão é a última migração.
-Idempotent	Gere um script que possa ser utilizado em um banco de dados em qualquer migração.
-NoTransactions	Não gera instruções de transação no SQL.
-Output <String>	O arquivo no qual gravar o resultado. Se esse parâmetro for omitido, o arquivo será criado com um nome gerado na mesma pasta que os arquivos de runtime do aplicativo são criados, por exemplo: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Os parâmetros comuns estão listados acima.

Tip

Os parâmetros To, From e Output dão suporte à expansão de tabulação.

O exemplo a seguir cria um script para a migração InitialCreate (a partir 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ções do banco de dados para a última migração ou para uma migração especificada.

Parameter	Description
-Migration <String>	O destino da migração. As migrações podem ser identificadas por nome ou por 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 tem como padrão a última migração.
-Connection <String>	A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou OnConfiguring.

Os parâmetros comuns estão listados acima.

Tip

O parâmetro Migration dá suporte à expansão de tabulação.

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

Update-Database 0

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

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

Additional resources

• Migrations
• Reverse Engineering
• Compiled models