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 --project.

• O 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

Opções comuns

Todos os argumentos adicionais são passados para o aplicativo.

dotnet ef database drop

Exclui o banco de dados.

Opções:

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:

Opções:

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 utilizado pelo DbContext.

Consulte Modelos compilados para obter mais informações.

Opções:

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:

Opções:

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:

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

dotnet ef migrations add

Adiciona uma nova migração.

Argumentos:

Opções:

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

dotnet ef migrations bundle

Cria um executável para atualizar o banco de dados.

Opções:

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

dotnet ef migrations has-pending-model-changes

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:

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:

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

dotnet ef migrations script

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

Argumentos:

Opções:

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

Recursos adicionais

• Migrações
• Engenharia reversa
• Modelos compilados