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

  • Artigo

As ferramentas do PMC (Console do gerenciador de pacotes) para o Entity Framework Core executam tarefas de desenvolvimento em tempo de design. Por exemplo, elas 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 do .NET Framework e o do .NET Core.

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 Core são multiplataformas e são executadas dentro de um prompt de comando.

Instalação das 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.>

Uso das 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 o projeto de destino porque é onde 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 precisam executar o código do aplicativo em tempo de design para obter informações sobre o projeto, como a cadeia de conexão 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 cenário comum no qual eles são projetos separados é quando:

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

Outras estruturas de destino

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 do .NET Standard podem não ter um projeto do .NET Core ou do .NET Framework. Por exemplo, isso se aplica aos aplicativos Xamarin e Plataforma Universal do Windows. Nesses casos, é possível criar um projeto de aplicativo de console do .NET Core ou do .NET Framework com o único propósito de atuar como projeto de inicialização para as ferramentas. Esse projeto de inicialização pode ser fictício, sem código real – sendo necessário apenas para fornecer um destino para as ferramentas.

Por que é necessário um projeto fictício? Conforme mencionado, as ferramentas precisam executar o código do aplicativo em tempo de design. Para fazer isso, eles precisam usar o runtime do .NET Core ou do .NET Framework. Quando o modelo do EF Core está em um projeto direcionado ao .NET Core ou ao .NET Framework, as ferramentas do EF Core emprestam o runtime do projeto. Elas não podem fazer isso se o modelo do EF Core estiver em uma biblioteca de classes do .NET Standard. O .NET Standard não é uma implementação .NET real, ele é uma especificação de um conjunto de APIs ao qual as implementações do .NET devem dar suporte. Portanto, o .NET Standard não é suficiente para que as ferramentas do EF Core executem o código do aplicativo. O projeto fictício criado para usar como projeto de inicialização fornece uma plataforma de destino concreta na qual as ferramentas podem carregar a biblioteca de classes do .NET Standard.

Ambiente do ASP.NET Core

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

Update-Database -Args '--environment Production'

Parâmetros comuns

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

Parâmetro Descrição
-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 saída detalhada.

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

Dica

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

Add-Migration

Adiciona uma nova migração.

Parâmetros:

Parâmetro Descrição
-Name <String> O nome da migração. Esse parâmetro é posicional e obrigatório.
-OutputDir <String> O diretório usa para gerar os arquivos. Os caminhos são relativos ao diretório do projeto de destino. O padrão é "Migrações".
-Namespace <String> O namespace usado 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.

Parâmetros:

Parâmetro Descrição
-Output <String> O caminho do arquivo executável a ser criado.
-Force Substitui os arquivos existentes.
-SelfContained Além disso, agrupe o runtime do .NET para que ele não precise ser instalado no computador.
-TargetRuntime <String> O runtime de destino para o qual agrupar.
-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.

Parâmetros:

Parâmetro Descrição
-WhatIf Mostra qual banco de dados seria descartado, mas não o remove.

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.

Parâmetros:

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

Os parâmetros comuns estão listados acima.

Optimize-DbContext

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

Confira os Modelos compilados para obter mais informações.

Parâmetros:

Parâmetro Descrição
-OutputDir <String> O diretório no qual 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 os CompiledModels.

Os parâmetros comuns estão listados acima.

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 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).

Parâmetros:

Parâmetro Descrição
-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 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.

Parâmetros:

Parâmetro Descrição
-Connection <String> A cadeia de conexão para o banco de dados. Para projetos do ASP.NET Core 2.x, o valor pode ser nome=<nome da cadeia de conexão>. Nesse caso, o nome tem origem nas fontes de configuração que são definidas 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 no qual colocar arquivos de classe de 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 a ser usado para todas as classes geradas. O padrão é 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. Observação: substitui -Namespace.
-Context <String> O nome da classe DbContext a ser gerada.
-Schemas <String[]> Os esquemas de tabelas e exibições para os quais 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 as quais 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 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 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 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 da configuração do projeto, possivelmente definida usando a ferramenta Gerenciador de Segredos.

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

Script-DbContext

Gera um script SQL do DbContext. Ignora as migrações.

Parâmetros:

Parâmetro Descrição
-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.

Parâmetros:

Parâmetro Descrição
-From <String> A migração inicial. As migrações podem ser identificadas por nome ou 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 em 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.

Dica

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.

Parâmetro Descrição
-Migration <String> O destino da migração. As migrações podem ser identificadas por nome ou 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.

Dica

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

Recursos adicionais