Referência das ferramentas principais do Entity Framework - CLI do .NET Core

Artigo
02/04/2025

As ferramentas de interface de linha de comando (CLI) para o 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 uma extensão ao comando dotnet multiplataforma, que faz parte do SDK .NET Core. Essas ferramentas funcionam com projetos .NET Core.

Ao usar o Visual Studio, considere usar as ferramentas do Console do Gerenciador de Pacotes em vez das ferramentas da CLI. Ferramentas da Consola do Gestor de Pacotes automaticamente:

Funciona com o projeto atual selecionado no Console do Gerenciador de Pacotes do sem exigir que você alterne manualmente os diretórios.
Abre arquivos gerados por um comando após a conclusão do comando.
Fornece preenchimento de guias de comandos, parâmetros, nomes de projetos, tipos de contexto e nomes de migração.

Instalação das ferramentas

dotnet ef pode ser instalado como uma ferramenta global ou local. A maioria dos desenvolvedores prefere instalar o dotnet ef como uma ferramenta global usando o seguinte comando:

dotnet tool install --global dotnet-ef

Para usá-lo como uma ferramenta local, restaure as dependências de um projeto que o declara como uma dependência de ferramentas usando um arquivo de manifesto da ferramenta .

Atualize a ferramenta usando o seguinte comando:

dotnet tool update --global dotnet-ef

Antes de poder usar 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 seguintes comandos para verificar se as ferramentas da CLI do EF 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 em seu projeto, use dotnet tool update dotnet-ef. Instale uma versão específica anexando --version <VERSION> ao comando. Consulte a seção Update da documentação da ferramenta dotnet para obter mais detalhes.

Utilização das ferramentas

Antes de usar as ferramentas, talvez seja necessário criar um projeto de inicialização ou definir o ambiente.

Projeto alvo e projeto de arranque

Os comandos referem-se a um projeto e a um projeto startup .

O projeto também é conhecido como o projeto de destino porque é onde 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 usando a opção --project.
O projeto de arranque é aquele que as ferramentas constroem e executam. As ferramentas têm que 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 no diretório atual é o projeto de inicialização. Você pode especificar um projeto diferente como projeto de inicialização usando a opção --startup-project.

O projeto inicial e o projeto-alvo são muitas vezes o mesmo projeto. Um cenário típico em que são projetos separados é quando:

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

Outros quadros-alvo

As ferramentas CLI funcionam com projetos .NET Core e projetos .NET Framework. Os aplicativos que têm o modelo EF Core em uma biblioteca de classes .NET Standard podem não ter um projeto .NET Core ou .NET Framework. Por exemplo, isso é verdade para aplicativos Xamarin e 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 — é necessário apenas fornecer um alvo para as ferramentas.

Importante

Xamarin.Android, Xamarin.iOS, Xamarin.Mac agora estão integrados diretamente ao .NET (começando com .NET 6) como .NET para Android, .NET para iOS e .NET para macOS. Se você estiver criando com esses tipos de projeto hoje, eles devem ser atualizados para projetos no estilo SDK do .NET para suporte contínuo. Para obter mais informações sobre como atualizar projetos Xamarin para .NET, consulte a documentação Upgrade from Xamarin to .NET & .NET MAUI.

Por que é necessário um projeto fictício? Como mencionado anteriormente, as ferramentas têm que executar o código da aplicação em tempo de conceção. Para fazer isso, eles precisam usar o tempo de execução do .NET Core. Quando o modelo EF Core está em um projeto destinado ao .NET Core ou .NET Framework, as ferramentas do EF Core tomam emprestado o tempo de execução do projeto. Eles não podem fazer isso se o modelo 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 que as implementações .NET devem suportar. Portanto, o .NET Standard não é suficiente para que as ferramentas 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 .NET Standard.

ASP.NET Ambiente central

Você pode especificar o ambiente para ASP.NET projetos principais na linha de comando. Este e quaisquer argumentos adicionais são passados para Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Dica

O token -- direciona dotnet ef a 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	Curto	Descrição
`--json`		Mostrar saída JSON.
`--context <DBCONTEXT>`	`-c`	A classe `DbContext` para usar. Nome da classe somente ou totalmente qualificado com namespaces. Se essa opção for omitida, o EF Core localizará a classe de contexto. Se houver várias classes de contexto, essa opção será necessária.
`--project <PROJECT>`	`-p`	Caminho relativo para a pasta do projeto de destino. O valor padrão é a pasta atual.
`--startup-project <PROJECT>`	`-s`	Caminho relativo até a pasta do projeto de arranque. O valor padrão é a pasta atual.
`--framework <FRAMEWORK>`		O Target Framework Moniker para a estrutura de destino . Use quando o arquivo de projeto especifica várias estruturas de destino e você deseja selecionar uma delas.
`--configuration <CONFIGURATION>`		A configuração de compilação, por exemplo: `Debug` ou `Release`.
`--runtime <IDENTIFIER>`		O identificador do tempo de execução de destino para o qual restaurar pacotes. Para obter uma lista de identificadores de tempo de execução (RIDs), consulte o catálogo RID.
`--no-build`		Não construa o projeto. Destina-se a ser usado quando a compilação estiver up-to-date.
`--help`	`-h`	Mostrar informações de ajuda.
`--verbose`	`-v`	Mostrar saída detalhada.
`--no-color`		Não colora a saída.
`--prefix-output`		Prefixar a saída com o nível.

Quaisquer argumentos adicionais são passados para o aplicativo.

`dotnet ef database drop`

Exclui o banco de dados.

Opções:

Opção	Curto	Descrição
`--force`	`-f`	Não confirme.
`--dry-run`		Mostre qual banco de dados seria descartado, mas não o solte.

As opções comuns estão listadas acima.

`dotnet ef database update`

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

Argumentos:

Argumento	Descrição
`<MIGRATION>`	A migração alvo. As migrações podem ser identificadas pelo nome ou pelo 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 assumirá como padrão a última migração.

Opções:

Opção	Descrição
`--connection <CONNECTION>`	A cadeia de conexão com o banco de dados. O padrão é o especificado em `AddDbContext` ou `OnConfiguring`.

As opções comuns estão listadas acima.

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 o ID de 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 de DbContext.

As opções comuns estão listadas acima.

`dotnet ef dbcontext list`

Lista os tipos de DbContext disponíveis.

As opções comuns estão listadas acima.

`dotnet ef dbcontext optimize`

Gera uma versão compilada do modelo usado pelo DbContext e pré-compila consultas.

Consulte Modelos compilados para obter mais informações.

Opções:

Opção	Curto	Descrição
`--output-dir <PATH>`	`-o`	O diretório para colocar arquivos. Os caminhos são relativos ao diretório do projeto.
`--namespace <NAMESPACE>`	`-n`	O namespace a ser usado para todas as classes geradas. Está definido para ser gerado a partir do namespace raiz e do diretório de saída mais `CompiledModels`.
`--suffix <SUFFIX>`		O sufixo para anexar ao nome de todos os ficheiros 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 consultas
`--nativeaot`		Gerar código adicional no modelo compilado necessário para compilação NativeAOT e consultas pré-compiladas

Observação

O suporte 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 usa as configurações padrão e funciona se houver 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 código para um DbContext e tipos de entidade para uma base de dados. Para que esse comando gere um tipo de entidade, a tabela do banco de dados deve ter uma chave primária.

Argumentos:

Argumento	Descrição
`<CONNECTION>`	A cadeia de conexão com o banco de dados. Para projetos ASP.NET Core 2.x, o valor pode ser name=<nome da string 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, este é o nome do pacote NuGet, por exemplo: `Microsoft.EntityFrameworkCore.SqlServer`.

Opções:

Opção	Curto	Descrição
`--data-annotations`	`-d`	Use atributos para configurar o modelo (sempre que possível). Se essa opção for omitida, somente a API fluente será usada.
`--context <NAME>`	`-c`	O nome da classe `DbContext` a ser gerada.
`--context-dir <PATH>`		O diretório para colocar o arquivo de 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 a ser usado para a classe `DbContext` gerada. Nota: substitui `--namespace`.
`--force`	`-f`	Substituir ficheiros existentes.
`--output-dir <PATH>`	`-o`	O diretório no qual colocar arquivos de classe de entidade. Os caminhos são relativos ao diretório do projeto.
`--namespace <NAMESPACE>`	`-n`	O namespace a ser usado para todas as classes geradas. Por defeito, é gerado a partir do namespace raiz e do diretório de saída.
`--schema <SCHEMA_NAME>...`		Os esquemas de tabelas e vistas para gerar tipos de entidade. Para especificar vários esquemas, repita `--schema` para cada um. Se essa opção for omitida, 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.
`--table <TABLE_NAME>...`	`-t`	As tabelas e exibições para gerar tipos de entidade. 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 esta opção for omitida, todas as tabelas e vistas serão incluídas.
`--use-database-names`		Use nomes de tabela, exibição, sequência e coluna exatamente como aparecem no banco de dados. Se essa opção for omitida, os nomes dos bancos de dados serão alterados para estarem mais em conformidade com as convenções de estilo de nome C#.
`--no-onconfiguring`		Suprime a geração do método `OnConfiguring` na classe `DbContext` gerada.
`--no-pluralize`		Não use o pluralizador.

As opções comuns estão listadas acima.

O exemplo a seguir estrutura todos os esquemas e tabelas e coloca os novos ficheiros na pasta Models.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

O exemplo a seguir gera apenas as tabelas selecionadas e cria o contexto numa pasta separada com um nome e espaço de nomes 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 usando a ferramenta Secret Manager.

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 andaime de um método OnConfiguring. Isso pode ser útil quando você deseja configurar o DbContext fora da classe. Por exemplo, ASP.NET aplicativos 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	Curto	Descrição
`--output <FILE>`	`-o`	O arquivo para gravar o resultado.

As opções comuns estão listadas acima.

`dotnet ef migrations add`

Adiciona uma nova migração.

Argumentos:

Argumento	Descrição
`<NAME>`	O nome da migração.

Opções:

Opção	Curto	Descrição
`--output-dir <PATH>`	`-o`	O diretório usado para saída dos arquivos. Os caminhos são relativos ao diretório do projeto alvo. O padrão é "Migrações".
`--namespace <NAMESPACE>`	`-n`	O namespace a ser usado para as classes geradas. O padrão é definido como 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	Curto	Descrição
`--output <FILE>`	`-o`	O caminho do arquivo executável a ser criado.
`--force`	`-f`	Substituir ficheiros existentes.
`--self-contained`		Além disso, agrupe o tempo de execução do .NET para que ele não precise ser instalado na máquina.
`--target-runtime <RUNTIME_IDENTIFIER>`	`-r`	O tempo de execução de destino para o qual agrupar.

As opções comuns estão listadas acima.

`dotnet ef migrations has-pending-model-changes`

Observação

Este comando foi adicionado no EF Core 8.0.

Verifica se foram feitas alterações 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 com o banco de dados. O padrão é o especificado em AddDbContext ou OnConfiguring.
`--no-connect`	Não se conecte 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	Curto	Descrição
`--force`	`-f`	Reverta a migração mais recente, revertendo as alterações de código e de banco de dados feitas para a migração mais recente. Continua a reverter apenas as alterações de código se ocorrer um erro durante a conexão com o banco de dados.

As opções comuns estão listadas acima.

`dotnet ef migrations script`

Gera um script SQL a partir de migrações.

Argumentos:

Argumento	Descrição
`<FROM>`	A migração inicial. As migrações podem ser identificadas pelo nome ou pelo ID. O número 0 é um caso especial que significa antes da primeira migração. O padrão é 0.
`<TO>`	O fim da migração. Define-se como padrão a última migração.

Opções:

Opção	Curto	Descrição
`--output <FILE>`	`-o`	O arquivo em que se deve gravar o script.
`--idempotent`	`-i`	Gere um script que pode ser usado em um banco de dados em qualquer migração.
`--no-transactions`		Não gere instruções de transação SQL.

As opções comuns estão listadas acima.

O exemplo a seguir 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

Partilhar via

Referência das ferramentas principais do Entity Framework - CLI do .NET Core

Instalação das ferramentas

Verificar a instalação

Atualizar as ferramentas

Utilização das ferramentas

Projeto alvo e projeto de arranque

Outros quadros-alvo

ASP.NET Ambiente central

Opções comuns

`dotnet ef database drop`

`dotnet ef database update`

`dotnet ef dbcontext info`

`dotnet ef dbcontext list`

`dotnet ef dbcontext optimize`

`dotnet ef dbcontext scaffold`

`dotnet ef dbcontext script`

`dotnet ef migrations add`

`dotnet ef migrations bundle`

`dotnet ef migrations has-pending-model-changes`

`dotnet ef migrations list`

`dotnet ef migrations remove`

`dotnet ef migrations script`

Recursos adicionais

Recursos adicionais