Referência de ferramentas de Entity Framework Core – console do Gerenciador de pacotes no Visual Studio

As ferramentas do console do Gerenciador de pacotes (PMC) para 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 o EF Core ferramentas de linha de comando . As ferramentas de CLI do .NET Core são entre plataformas 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 é parecida com esta (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 destino e o projeto de inicialização.
  • Saiba como usar as ferramentas com .NET Standard bibliotecas de classe.
  • Para projetos ASP.NET Core, defina o ambiente.

Projeto de destino e inicialização

Os comandos referem-se a um projeto e 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 a --project opção.

  • 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 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 a --startup-project opção.

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

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

Outras estruturas de destino

As ferramentas de console do Gerenciador de pacotes funcionam com projetos .NET Core ou .NET Framework. Os aplicativos que têm o modelo de EF Core em uma biblioteca de classes de .NET Standard podem não ter um projeto do .NET Core ou do .NET Framework. Por exemplo, isso é verdadeiro para aplicativos Xamarin e Plataforma Universal do Windows. Nesses casos, você pode criar um projeto de aplicativo de console do .NET Core ou .NET Framework, cujo único propósito é agir 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 o .NET Framework Runtime. Quando o modelo de EF Core está em um projeto direcionado ao .NET Core ou .NET Framework, as ferramentas de EF Core emprestam o tempo de execução do projeto. Eles não poderão fazer isso se o modelo de 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 para as quais as implementações do .NET devem dar suporte. Portanto .NET Standard não é suficiente para as ferramentas de EF Core executarem 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 o .NET Standard biblioteca de classes.

Ambiente de ASP.NET Core

Para especificar o ambiente para projetos de ASP.NET Core, defina env: ASPNETCORE_ENVIRONMENT antes de executar os 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 os parâmetros que são comuns a todos os comandos de EF Core:

Parâmetro Descrição
-Contexto <String> A classe DbContext a ser usada. Nome da classe somente ou totalmente qualificado com namespaces. Se esse parâmetro for omitido, EF Core encontrará a classe de contexto. Se houver várias classes de contexto, esse parâmetro será necessário.
-Projeto <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. Adicionado no EF Core 5,0.
-Verbose Mostrar saída detalhada.

Para mostrar informações de ajuda sobre um comando, use o Get-Help comando 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
-Nome <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.

Drop-Database

Remove o banco de dados.

Parâmetros:

Parâmetro Descrição
-WhatIf Mostrar qual banco de dados seria descartado, mas não descartá-lo.

Os parâmetros comuns são listados acima.

Get-DbContext

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

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
-Conexão <String> A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou onconfiguring.
-Noconnect Não se conecte ao banco de dados.

Os parâmetros comuns são listados acima.

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 são listados acima.

Scaffold-DbContext

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

Parâmetros:

Parâmetro Descrição
-Conexão <String> A cadeia de conexão para o banco de dados. Para projetos ASP.NET Core 2. x, o valor pode ser nome = <name of connection string>. Nesse caso, o nome é proveniente das fontes de configuração que estão configuradas para o projeto. Esse é um parâmetro posicional e é necessário.
-Provedor <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. Os caminhos são relativos ao diretório do projeto.
-ContextDir <String> O diretório no qual 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 DbContext classe gerada. Observação: substituições -Namespace . Adicionado no EF Core 5,0.
-Contexto <String> O nome da DbContext classe a ser gerada.
-Esquemas <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.
-Tabelas <String[]> As tabelas para as quais gerar tipos de entidade. Se esse parâmetro for omitido, todas as tabelas serão incluídas.
-Annotations 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 se adequar melhor às convenções de estilo de nome C#.
-Force Substitui os arquivos existentes.
-NoOnConfiguring Não gerar DbContext.OnConfiguring . Adicionado no EF Core 5,0.
-Despluralize Não use o pluralizer. 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 que aplica Scaffold apenas 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 segredo.

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

Script-DbContext

Gera um script SQL do DbContext. Ignora todas as migrações. Adicionado no EF Core 3,0.

Parâmetros:

Parâmetro Descrição
-Saída <String> O arquivo no qual o resultado será gravado.

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
-De<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.
-Para<String> A migração final. O padrão é a última migração.
-Idempotente Gere um script que possa ser usado em um banco de dados em qualquer migração.
-Transtransações Não gere instruções de transação SQL. Adicionado no EF Core 5,0.
-Saída <String> O arquivo no qual o resultado será gravado. Se esse parâmetro for omitido, o arquivo será criado com um nome gerado na mesma pasta 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 são listados acima.

Dica

Os parâmetros para, de e saída 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 nenhuma migração), usando o nome de 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 o banco de dados para a última migração ou para uma migração especificada.

Parâmetro Descrição
-Migração<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 usa como padrão a última migração.
-Conexão <String> A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou OnConfiguring . Adicionado no EF Core 5,0.

Os parâmetros comuns são listados acima.

Dica

O parâmetro de migração oferece 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 de 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