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

As ferramentas da CLI (interface de linha de comando) para Entity Framework Core executar 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 para o comando dotnet de plataforma cruzada, que faz parte do SDK do .NET Core. Essas ferramentas funcionam com projetos do .NET Core.

Ao usar o Visual Studio, considere o uso das ferramentas de console do Gerenciador de pacotes no lugar das ferramentas da CLI. Ferramentas de console do Gerenciador de pacotes automaticamente:

  • Funciona 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 preenchimento com Tab de comandos, parâmetros, nomes de projeto, tipos de contexto e nomes de migração.

Instalando as ferramentas

dotnet ef o pode ser instalado como uma ferramenta global ou local. A maioria dos desenvolvedores prefere dotnet ef a instalação 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 a declare 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

Para poder usar as ferramentas em um projeto específico, você precisará adicionar o Microsoft.EntityFrameworkCore.Design pacote a ela.

dotnet add package Microsoft.EntityFrameworkCore.Design

Verifique 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 no seu projeto, use dotnet tool update dotnet-ef . Instale uma versão específica anexando --version <VERSION> ao comando. Consulte a seção atualização da documentação da ferramenta dotnet para obter mais detalhes.

Usando as ferramentas

Antes de usar as ferramentas, talvez seja necessário 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 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 no diretório atual é 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 no diretório atual é 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 da CLI funcionam com projetos do .NET Core e .NET Framework projetos. 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 cuja única finalidade é 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 tempo de execução do .NET Core. 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 a variável de ambiente 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:

dotnet ef database update -- --environment Production

Dica

O -- token direciona dotnet ef para tratar tudo o que segue como um argumento e não tentar analisá-los como opções. Quaisquer argumentos extras não usados pelo dotnet ef são encaminhados para o aplicativo.

Opções comuns

Opção Short Descrição
--json Mostrar saída JSON.
--context <DBCONTEXT> -c A classe DbContext a ser usada. Nome da classe somente ou totalmente qualificado com namespaces. Se essa opção for omitida, EF Core encontrará 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 para a pasta 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 de projeto especificar várias estruturas de destino e você desejar selecionar uma delas.
--configuration <CONFIGURATION> A configuração de Build, por exemplo: Debug ou Release .
--runtime <IDENTIFIER> O identificador do tempo de execução 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 compile o projeto. Destinado a ser usado quando a compilação está atualizada.
--help -h Mostrar informações de ajuda.
--verbose -v Mostrar saída detalhada.
--no-color Não colorir a saída.
--prefix-output Saída de prefixo com nível.

A partir do EF Core 5,0, 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 confirme.
--dry-run Mostrar qual banco de dados seria descartado, mas não descartá-lo.

As opções comuns sã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 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.

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 . Adicionado no EF Core 5,0.

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

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:

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

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

dotnet ef dbcontext list

Lista os DbContext tipos disponíveis.

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

dotnet ef dbcontext scaffold

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

Argumentos:

Argumento Descrição
<CONNECTION> 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.
<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 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 DbContext classe a ser gerada.
--context-dir <PATH> O diretório no qual colocar o DbContext arquivo de classe. Os caminhos são relativos ao diretório do projeto. Os namespaces são derivados dos nomes de pasta.
--context-namespace <NAMESPACE> O namespace a ser usado para a DbContext classe gerada. Observação: substituições --namespace . Adicionado no EF Core 5,0.
--force -f Substitui os arquivos existentes.
--output-dir <PATH> -o O diretório no qual colocar os 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. O padrão é gerado a partir do namespace raiz e do diretório de saída. Adicionado no EF Core 5,0.
--schema <SCHEMA_NAME>... Os esquemas de tabelas para os quais 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.
--table <TABLE_NAME>... -t As tabelas para as quais gerar tipos de entidade. Para especificar várias tabelas, repita -t ou --table para cada uma delas. Se essa opção for omitida, todas as tabelas serão incluídas.
--use-database-names Use nomes de tabela e coluna exatamente como aparecem no banco de dados. Se essa opção for omitida, os nomes de banco de dados serão alterados para mais de acordo com as convenções de estilo de nome C#.
--no-onconfiguring Suprime a geração do OnConfiguring método na classe gerada DbContext . Adicionado no EF Core 5,0.
--no-pluralize Não use o pluralizer. Adicionado no EF Core 5,0

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

O exemplo a seguir aplica Scaffold 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 aplica Scaffold apenas 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 usando a ferramenta Gerenciador de segredo.

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 scaffolding um OnConfiguring método. Isso pode ser útil quando você deseja configurar o DbContext fora da classe. Por exemplo, ASP.NET Core aplicativos normalmente o configuram em Startup.ConfigureServices. Adicionado no EF Core 5,0.

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 do DbContext. Ignora todas as migrações. Adicionado no EF Core 3,0.

Opções:

Opção Short Descrição
--output <FILE> -o O arquivo no qual o resultado será gravado.

As opções comuns sã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 Short Descrição
--output-dir <PATH> -o 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 <NAMESPACE> -n 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.

As opções comuns sã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. Adicionado no EF Core 5,0.
--no-connect Não se conecte ao banco de dados. Adicionado no EF Core 5,0.

As opções comuns sã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 Reverta a migração mais recente, revertendo as alterações de código e de banco de dados que foram feitas para a migração mais recente. Continua revertendo apenas as alterações de código se ocorrer um erro durante a conexão com o banco de dados.

As opções comuns sã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 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 no qual gravar o script.
--idempotent -i Gere um script que possa ser usado em um banco de dados em qualquer migração.
--no-transactions Não gere instruções de transação SQL. Adicionado no EF Core 5,0.

As opções comuns sã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 de InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Recursos adicionais