referência Entity Framework Core ferramentas de 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 Visual Studio, considere usar as ferramentas Gerenciador de Pacotes Console em vez das ferramentas da CLI. Gerenciador de Pacotes console automaticamente:

  • Funciona com o projeto atual selecionado no console Gerenciador de Pacotes sem a necessidade de alternar manualmente os diretórios.
  • Abre os arquivos gerados por um comando após a conclusão do comando.
  • Fornece preenchimento de guias de comandos, parâmetros, nomes de projeto, tipos de contexto e nomes de migração.

Instalando as ferramentas

dotnet ef pode ser instalado como uma ferramenta global ou local. A maioria dos desenvolvedores prefere dotnet ef instalar 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 usar as ferramentas em um projeto específico, você precisará adicionar o Microsoft.EntityFrameworkCore.Design pacote a ele.

dotnet add package Microsoft.EntityFrameworkCore.Design

Verificar a instalação

Execute os seguintes comandos para verificar se as EF Core CLI 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, ao fazer a --version <VERSION> adoção do comando . Confira a seção Atualizar da documentação da ferramenta dotnet para obter mais detalhes.

Usando as ferramentas

Antes de usar as ferramentas, talvez seja preciso 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 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 são construídas e executados. 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 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 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 eles são projetos separados é quando:

  • As EF Core de contexto e 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 EF Core .

Outras estruturas de destino

As ferramentas da CLI funcionam com projetos do .NET Core e .NET Framework projetos. Aplicativos que têm o EF Core em uma biblioteca de classes .NET Standard podem não ter um projeto .NET Core ou .NET Framework aplicativo. Por exemplo, isso se aplica aos aplicativos Xamarin e Universal Windows Platform. Nesses casos, você pode criar um projeto de aplicativo de console do .NET Core cuja única finalidade é atuar como um 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 têm que executar o código do aplicativo em tempo de design. Para fazer isso, eles precisam usar o runtime do .NET Core. Quando o EF Core está em um projeto destinado ao .NET Core ou .NET Framework, as ferramentas EF Core o runtime do projeto. Eles não poderão fazer isso se o modelo EF Core estiver em uma biblioteca .NET Standard de classes. 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, .NET Standard é suficiente para as ferramentas EF Core para executar o código do aplicativo. O projeto fictício criado para usar como projeto de inicialização fornece uma plataforma de destino concreta na qual as ferramentas podem carregar a .NET Standard de classes.

ASP.NET Core ambiente

Para especificar o ambiente para ASP.NET Core, de acordo com a variável ASPNETCORE_ENVIRONMENT de ambiente antes de executar comandos.

Começando no 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 para tratar tudo o que segue como um argumento e não tentar analisar --dotnet ef como opções. Todos os 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 de 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 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ê quiser selecionar uma delas.
--configuration <CONFIGURATION> A configuração de build, por exemplo: Debug ou Release .
--runtime <IDENTIFIER> O identificador do runtime de destino para o que restaurar pacotes. Para obter uma lista de RIDs (Identificadores de Runtime), veja o Catálogo de RIDs.
--no-build Não crie o projeto. Destina-se a ser usado quando o build está atualizado.
--help -h Mostrar informações de ajuda.
--verbose -v Mostrar saída detalhada.
--no-color Não colorize a saída.
--prefix-output Saída de prefixo com nível.

A partir 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 Mostre qual banco de dados seria descartado, mas não o solte.

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 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 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 da 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 tipos DbContext disponíveis.

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

dotnet ef dbcontext optimize

Gera uma versão compilada do modelo usado pelo DbContext . Adicionado no EF Core 6.

Consulte Modelos compilados para obter mais informações.

Opções:

Opção Short Descrição
--output-dir <PATH> -o O diretório no qual 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. O padrão é gerado do namespace raiz e do diretório de saída mais CompiledModels .

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

O exemplo a seguir usa as configurações padrão e funciona se houver apenas DbContext uma 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 tipos de DbContext 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 ASP.NET Core projetos 2.x, o valor pode ser name= name= name > da cadeia de conexão. Nesse caso, o nome vem das fontes de configuraçã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 gerado.
--context-dir <PATH> O diretório no qual colocar DbContext o 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 classe DbContext gerada. Observação: substitui --namespace . Adicionado no EF Core 5.0.
--force -f Substitui os arquivos 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. O padrão é gerado 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 para cada uma --table 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 estar mais em conformidade com as convenções de estilo de nome C#.
--no-onconfiguring Suprime a geração OnConfiguring do método na classe DbContext gerada. Adicionado no EF Core 5.0.
--no-pluralize Não use o pluralizador. Adicionado no EF Core 5.0

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

O exemplo a seguir faz scaffold de 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 faz scaffolds apenas de tabelas selecionadas e cria o contexto em uma pasta separada com um nome e um 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 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 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 as migrações.

Opções:

Opção Short Descrição
--output <FILE> -o O arquivo no que gravar o resultado.

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 usa para 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 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 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 a ser criado.
--force -f Substitui os arquivos existentes.
--self-contained Além disso, agrupe o tempo de execução do .NET para que ele não precise ser instalado no computador.
--target-runtime <RUNTIME_IDENTIFIER> -r O tempo de execução de destino para o qual agrupar.

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 de SQL 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 SQL instruções de transação. 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