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, 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.
Aviso
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 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
-ProjectO 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 típico cenário em que eles são projetos separados é quando:
- As classes de contexto e entidade do Entity Framework Core estão em uma biblioteca de classes .NET Core.
- Um aplicativo Web ou aplicativo de console .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 Entity Framework 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 um projeto fictício é obrigatório? 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 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 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 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.
Parâmetros:
| Parâmetro | Descrição |
|---|---|
-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 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 é aquele 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 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 os CompiledModels. |
Os parâmetros comuns estão listados acima.
Observação
Atualmente, 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 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. 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 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 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 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 usando Configuração.
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 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 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 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.
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
