Referência das ferramentas do Entity Framework Core - CLI do .NET Core
As ferramentas da interface de linha de comando (CLI) do 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 uma extensão do comando entre plataformas dotnet, que faz parte do SDK do .NET Core. Essas ferramentas funcionam com projetos do .NET Core.
Ao usar o Visual Studio, considere utilizar as ferramentas de console do Gerenciador de Pacotes em vez das ferramentas da CLI. Ferramentas do Console do Gerenciador de Pacotes automaticamente:
- Funcionam com o projeto atual selecionado no Console do Gerenciador de Pacotes sem exigir que você alterne manualmente os diretórios.
- Abre os arquivos gerados por um comando após a conclusão do comando.
- Fornece o conclusão de guias de comandos, parâmetros, nomes de projetos, tipos de contexto e nomes de migração.
Instalação das ferramentas
O dotnet ef pode ser instalado como uma ferramenta global ou local. A maioria dos desenvolvedores prefere instalar dotnet ef como uma ferramenta global usando o seguinte comando:
dotnet tool install --global dotnet-ef
Você também pode obtê-lo como uma ferramenta local quando você restaura as dependências de um projeto que o declara como uma dependência de ferramentas usando um arquivo de manifesto de ferramenta.
Atualizações da ferramenta utilizando o seguinte comando:
dotnet tool update --global dotnet-ef
Antes de poder utilizar as ferramentas em um projeto específico, você precisará adicionar o pacote Microsoft.EntityFrameworkCore.Design a ele.
dotnet add package Microsoft.EntityFrameworkCore.Design
Verificar a instalação
Execute os comandos a seguir para verificar se as ferramentas da CLI do Entity Framework Core estão instaladas corretamente:
dotnet ef
A saída do comando identifica a versão das ferramentas em uso:
_/\__
---==/ \\
___ ___ |. \|\
| __|| __| | ) \\\
| _| | _| \_/ | //|\\
|___||_| / \\\/\\
Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065
<Usage documentation follows, not shown.>
Atualizar as ferramentas
Use dotnet tool update --global dotnet-ef para atualizar as ferramentas globais para a versão mais recente disponível. Se você tiver as ferramentas instaladas localmente no seu projeto, utilize dotnet tool update dotnet-ef. Instale uma versão específica acrescentando --version <VERSION> ao seu comando. Consulte a seção Atualizar da documentação da ferramenta dotnet para obter mais detalhes.
Usando as ferramentas
Antes de usar as ferramentas, talvez você deva criar um projeto de inicialização ou definir o ambiente.
Projeto de destino e projeto 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 no diretório atual é o projeto de destino. Você pode especificar um projeto diferente como projeto de destino utilizando a opção
--projectO 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 no diretório atual é o projeto de inicialização. Você pode especificar um projeto diferente como projeto de inicialização utilizando a opção
--startup-project
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 da CLI funcionam com projetos .NET Core e projetos .NET Framework. Os aplicativos que têm o modelo Entity Framework 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 o Xamarin e a Plataforma Universal do Windows. Nesses casos, você pode criar um projeto de aplicativo de console .NET Core 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 é obrigatório? Conforme mencionado anteriormente, as ferramentas devem executar o código do aplicativo em tempo de design. Para isso, eles precisam utilizar o runtime do .NET Core. Quando o modelo Entity Framework Core está em um projeto que tem como destino o .NET Core ou o .NET Framework, as ferramentas do Entity Framework Core pegam emprestado 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.
dotnet ef database update -- --environment Production
Dica
O token -- direciona dotnet ef para tratar tudo o que se segue como um argumento e não tentar analisá-los como opções. Todos os argumentos extras não usados por dotnet ef são encaminhados para o aplicativo.
Opções comuns
| Opção | Short | Descrição |
|---|---|---|
--json |
Mostrar a saída JSON. | |
--context <DBCONTEXT> |
-c |
A classe DbContext a ser usada. Somente nome de classe ou totalmente qualificado com namespaces. Se essa opção for omitida, o Entity Framework Core encontrará a classe de contexto. Se existirem várias classes de contexto, essa opção será obrigatória. |
--project <PROJECT> |
-p |
Caminho relativo à pasta do projeto do projeto de destino. O valor padrão é a pasta atual. |
--startup-project <PROJECT> |
-s |
Caminho relativo à pasta do projeto do projeto de inicialização. O valor padrão é a pasta atual. |
--framework <FRAMEWORK> |
O Moniker da Estrutura de Destino para a estrutura de destino. Use quando o arquivo do projeto especificar várias estruturas de destino e você desejar selecionar uma delas. | |
--configuration <CONFIGURATION> |
A configuração da compilação, por exemplo: Debug ou Release. |
|
--runtime <IDENTIFIER> |
O identificador do runtime de destino para o qual restaurar os pacotes. Para obter uma lista de RIDs (Identificadores de Runtime), veja o Catálogo de RIDs. | |
--no-build |
Não compilar o projeto. Destina-se a ser utilizado quando a compilação estiver atualizada. | |
--help |
-h |
Mostra informações da Ajuda. |
--verbose |
-v |
Mostrar a saída detalhada. |
--no-color |
Não colorir a saída. | |
--prefix-output |
Prefixar a saída com o nível. |
Todos os argumentos adicionais são passados para o aplicativo.
dotnet ef database drop
Exclui o banco de dados.
Opções:
| Opção | Short | Descrição |
|---|---|---|
--force |
-f |
Não confirmar. |
--dry-run |
Mostre qual banco de dados seria removido, mas não o remova. |
As opções comuns estão listadas acima.
dotnet ef database update
Atualizações do banco de dados para a última migração ou para uma migração especificada.
Argumentos:
| Argument | Descrição |
|---|---|
<MIGRATION> |
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. |
Opções:
| Opção | Descrição |
|---|---|
--connection <CONNECTION> |
A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou OnConfiguring. |
As opções comuns estão listadas acima.
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:
dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string
dotnet ef dbcontext info
Obtém informações sobre um tipo DbContext.
As opções comuns estão listadas acima.
dotnet ef dbcontext list
Lista os tipos disponíveis de DbContext.
As opções comuns estão listadas acima.
dotnet ef dbcontext optimize
Gera uma versão compilada do modelo usado pelas DbContext consultas e pré-compila.
Consulte Modelos compilados para obter mais informações.
Opções:
| Opção | Short | Descrição |
|---|---|---|
--output-dir <PATH> |
-o |
O diretório em que os arquivos serão colocados. Os caminhos são relativos ao diretório do projeto. |
--namespace <NAMESPACE> |
-n |
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. |
--suffix <SUFFIX> |
O sufixo a ser anexado ao nome de todos os arquivos gerados. Por exemplo, .g pode ser usado para indicar que esses arquivos contêm código gerado |
|
--no-scaffold |
Não gere um modelo compilado. Isso é usado quando o modelo compilado já foi gerado. | |
--precompile-queries |
Gere consultas pré-compiladas. Isso é necessário para a compilação NativeAOT se o projeto de destino contiver alguma consulta | |
--nativeaot |
Gerar código adicional no modelo compilado necessário para compilação NativeAOT e consultas pré-compiladas |
Observação
O suporte a NativeAOT e as consultas pré-compiladas são considerados experimentais no EF 9 e podem mudar drasticamente na próxima versão.
As opções comuns estão listadas acima.
O exemplo a seguir utiliza as configurações padrão e funciona se existir apenas um DbContext no projeto:
dotnet ef dbcontext optimize
O exemplo a seguir otimiza o modelo para o contexto com o nome especificado e o coloca em uma pasta e namespace separados:
dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext
dotnet ef dbcontext scaffold
Gera o código para um DbContext e tipos de entidade para um banco de dados. Para que esse comando gere um tipo de entidade, a tabela do banco de dados deve ter uma chave primária.
Argumentos:
| Argument | Descrição |
|---|---|
<CONNECTION> |
A cadeia de conexão para o banco de dados. Para projetos ASP.NET Core 2.x, o valor pode ser name=<nome da cadeia de conexão>. Nesse caso, o nome vem das fontes de configuração que estão configuradas para o projeto. |
<PROVIDER> |
O provedor a ser usado. Normalmente, esse é o nome do pacote NuGet, por exemplo: Microsoft.EntityFrameworkCore.SqlServer. |
Opções:
| Opção | Short | Descrição |
|---|---|---|
--data-annotations |
-d |
Usar atributos para configurar o modelo (sempre que possível). Se essa opção for omitida, somente a API fluente será utilizada. |
--context <NAME> |
-c |
O nome da classe DbContext que será gerada. |
--context-dir <PATH> |
O diretório no qual será colocado o arquivo da classe DbContext. Os caminhos são relativos ao diretório do projeto. Os namespaces são derivados dos nomes das pastas. |
|
--context-namespace <NAMESPACE> |
O namespace que será utilizado para a classe DbContext gerada. Observação: substitui --namespace. |
|
--force |
-f |
Substitui os arquivos existentes. |
--output-dir <PATH> |
-o |
O diretório para colocar os arquivos de classe da entidade. Os caminhos são relativos ao diretório do projeto. |
--namespace <NAMESPACE> |
-n |
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. |
--schema <SCHEMA_NAME>... |
Os esquemas de tabelas e exibições para os quais gerar tipos de entidades. Para especificar vários esquemas, repita --schema para cada um deles. Se essa opção for omitida, 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. |
|
--table <TABLE_NAME>... |
-t |
As tabelas e exibições para as quais gerar tipos de entidades. Para especificar várias tabelas, repita -t ou --table para cada uma delas. Tabelas ou exibições em um esquema específico podem ser incluídas usando o formato "schema.table" ou "schema.view". Se essa opção for omitida, todas as tabelas e exibições serão incluídas. |
--use-database-names |
Usar nomes de tabelas, exibições, sequências e colunas exatamente como aparecem no banco de dados. Se essa opção for omitida, os nomes dos bancos de dados serão alterados para se adequarem melhor às convenções de nomenclatura do C#. | |
--no-onconfiguring |
Suprime a geração do método OnConfiguring na classe DbContext gerada. |
|
--no-pluralize |
Não utilize o pluralizador. |
As opções comuns estão listadas acima.
O exemplo a seguir gera estruturas para todos os esquemas e tabelas e coloca os novos arquivos na pasta Modelos.
dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models
O exemplo a seguir gera estruturas apenas para tabelas selecionadas e cria o contexto em uma pasta separada com um nome e namespace especificados:
dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models -t Blog -t Post --context-dir Context -c BlogContext --context-namespace New.Namespace
O exemplo a seguir lê a cadeia de conexão do conjunto de configurações do projeto utilizando a ferramenta Gerenciador de segredos.
dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer
O exemplo a seguir ignora o scaffolding de um método OnConfiguring. Isso pode ser útil quando você deseja configurar o DbContext fora da classe. Por exemplo, os aplicativos ASP.NET Core normalmente o configuram em Startup.ConfigureServices.
dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring
dotnet ef dbcontext script
Gera um script SQL a partir do DbContext. Ignora quaisquer migrações.
Opções:
| Opção | Short | Descrição |
|---|---|---|
--output <FILE> |
-o |
O arquivo no qual gravar o resultado. |
As opções comuns estão listadas acima.
dotnet ef migrations add
Adiciona uma nova migração.
Argumentos:
| Argument | Descrição |
|---|---|
<NAME> |
O nome da migração. |
Opções:
| Opção | Short | Descrição |
|---|---|---|
--output-dir <PATH> |
-o |
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 <NAMESPACE> |
-n |
O namespace que será utilizado para as classes geradas. O padrão é gerado a partir do diretório de saída. |
As opções comuns estão listadas acima.
dotnet ef migrations bundle
Cria um executável para atualizar o banco de dados.
Opções:
| Opção | Short | Descrição |
|---|---|---|
--output <FILE> |
-o |
O caminho do arquivo executável que será criado. |
--force |
-f |
Substitui os arquivos existentes. |
--self-contained |
Também agrupa o runtime do .NET para que ele não precise ser instalado no computador. | |
--target-runtime <RUNTIME_IDENTIFIER> |
-r |
O runtime de destino para o qual o pacote deve ser feito. |
As opções comuns estão listadas acima.
dotnet ef migrations has-pending-model-changes
Observação
Esse comando foi adicionado no EF Core 8.0.
Verifica se alguma alteração foi feita no modelo desde a última migração.
Opções:
As opções comuns estão listadas acima.
dotnet ef migrations list
Lista as migrações disponíveis.
Opções:
| Opção | Descrição |
|---|---|
--connection <CONNECTION> |
A cadeia de conexão para o banco de dados. O padrão é aquele especificado em AddDbContext ou OnConfiguring. |
--no-connect |
Não se conectar ao banco de dados. |
As opções comuns estão listadas acima.
dotnet ef migrations remove
Remove a última migração, revertendo as alterações de código que foram feitas para a migração mais recente.
Opções:
| Opção | Short | Descrição |
|---|---|---|
--force |
-f |
Reverte a última migração, revertendo as alterações de código e de banco de dados que foram feitas para a última migração. Continua a reverter apenas as alterações de código se ocorrer um erro ao se conectar ao banco de dados. |
As opções comuns estão listadas acima.
dotnet ef migrations script
Gera um script SQL a partir das migrações.
Argumentos:
| Argument | Descrição |
|---|---|
<FROM> |
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> |
A migração final. O padrão é a última migração. |
Opções:
| Opção | Short | Descrição |
|---|---|---|
--output <FILE> |
-o |
O arquivo em que o script será gravado. |
--idempotent |
-i |
Gere um script que possa ser utilizado em um banco de dados em qualquer migração. |
--no-transactions |
Não gera instruções de transação no SQL. |
As opções comuns estão listadas acima.
O seguinte exemplo cria um script para a migração InitialCreate:
dotnet ef migrations script 0 InitialCreate
O exemplo a seguir cria um script para todas as migrações após a migração InitialCreate.
dotnet ef migrations script 20180904195021_InitialCreate
