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) do Entity Framework Core executam tarefas de desenvolvimento em tempo 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 do .NET Framework e o do .NET Core.

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

Instalando 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

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

Usando 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.
  • Para projetos ASP.NET Core, defina o ambiente.

Projeto de destino e 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 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 -Project parâmetro.

  • 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 no Gerenciador de Soluções é o projeto de inicialização. Você pode especificar um projeto diferente como projeto de inicialização usando o -StartupProject parâmetro.

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

  • As classes de entidade e contexto EF Core estão em uma biblioteca de classes do .NET Core.
  • Um aplicativo de console ou aplicativo Web .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 do .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 .NET Core ou .NET Framework. Por exemplo, isso se aplica aos aplicativos Xamarin e Plataforma Universal do Windows. Nesses casos, você pode criar um projeto de aplicativo de console do .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 – ele só é necessário para fornecer um destino para as ferramentas.

Por que um projeto fictício é necessário? Conforme mencionado anteriormente, as ferramentas precisam executar o código do aplicativo em tempo de design. Para fazer isso, eles precisam usar o .NET Core ou .NET Framework runtime. Quando o modelo do EF Core está em um projeto direcionado ao .NET Core ou .NET Framework, as ferramentas do EF Core emprestam o runtime do projeto. Eles não poderão 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; é 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 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 do .NET Standard.

ambiente ASP.NET Core

Para especificar o ambiente para projetos ASP.NET Core, defina env:ASPNETCORE_ENVIRONMENT antes de executar comandos.

A partir do EF Core 5.0, argumentos adicionais também podem ser passados para Program.CreateHostBuilder, permitindo que você especifique o ambiente na linha de comando:

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 da classe 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 de destino. 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 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. Adicionado no EF Core 5.0.
-Verbose Mostrar saída detalhada.

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

Dica

Os Contextparâmetros e StartupProject os Projectparâmetros 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 é um parâmetro posicional e é necessário.
-OutputDir <String> O diretório é usado 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 a ser usado para as classes geradas. O padrão é gerado a partir do diretório de saída. Adicionado no EF Core 5.0.

Os parâmetros comuns sã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 Adicione também 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 são listados acima.

Drop-Database

Remove o banco de dados.

Parâmetros:

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

Os parâmetros comuns são listados acima.

Get-DbContext

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

Os parâmetros comuns são listados acima.

Get-Migration

Lista as migrações disponíveis. Adicionado no EF Core 5.0.

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 conecte ao banco de dados.

Os parâmetros comuns são listados acima.

Optimize-DbContext

Gera uma versão compilada do modelo usado pelo DbContext. Adicionado no EF Core 6.

Confira os 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 sã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 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 Reverta a migração (reverta as alterações aplicadas ao banco de dados).

Os parâmetros comuns são listados acima.

Scaffold-DbContext

Gera código para tipos de entidade e um DbContext código 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 de ASP.NET Core 2.x, o valor pode ser name=<name da cadeia de conexão>. Nesse caso, o nome vem das fontes de configuração configuradas para o projeto. Esse é um parâmetro posicional e é necessário.
-Provider <String> O provedor a ser usado. Normalmente, esse é o nome do pacote NuGet, por exemplo: Microsoft.EntityFrameworkCore.SqlServer. Esse é um parâmetro posicional e é necessá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 DbContext arquivo. 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. Adicionado no EF Core 5.0.
-ContextNamespace <String> O namespace a ser usado para a classe gerada DbContext . Observação: substituições -Namespace. Adicionado no EF Core 5.0.
-Context <String> O nome da classe a DbContext ser gerada.
-Schemas <String[]> Os esquemas de tabelas para os quais gerar tipos de entidade. Se esse parâmetro for omitido, todos os esquemas serão incluídos.
-Tables <String[]> As tabelas para as quais gerar tipos de entidade. Se esse parâmetro for omitido, todas as tabelas 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 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 estar mais próximos das convenções de estilo de nome C#.
-Force Substitui os arquivos existentes.
-NoOnConfiguring Não gere DbContext.OnConfiguring. Adicionado no EF Core 5.0.
-NoPluralize Não use o pluralizador. Adicionado no EF Core 5.0.

Os parâmetros comuns são listados acima.

Exemplo:

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

Exemplo de que scaffolds apenas selecionou tabelas e cria o contexto em uma 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 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 todas as migrações.

Parâmetros:

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

Os parâmetros comuns sã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 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 pode ser usado em um banco de dados em qualquer migração.
-NoTransactions Não gere instruções de transação SQL. Adicionado no EF Core 5.0.
-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 são listados acima.

Dica

Os Toparâmetros e Output os Fromparâmetros dão suporte à expansão de 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 de InitialCreate, usando a ID de migração.

Script-Migration 20180904195021_InitialCreate

Update-Database

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

Parâmetro Descrição
-Migration <String> A migração de destino. 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 será padronizado para a última migração.
-Connection <String> A cadeia de conexão para o banco de dados. O padrão é o especificado em AddDbContext ou OnConfiguring. Adicionado no EF Core 5.0.

Os parâmetros comuns são listados acima.

Dica

O Migration parâmetro dá suporte à 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 a ID de migração e uma conexão especificada:

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

Recursos adicionais