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

As ferramentas de interface de linha de comando (CLI) para o Entity Framework Core realizar tarefas de desenvolvimento de tempo de design.The command-line interface (CLI) tools for Entity Framework Core perform design-time development tasks. Por exemplo, eles criam migrações, aplicar as migrações e gerar código para um modelo com base em um banco de dados existente.For example, they create migrations, apply migrations, and generate code for a model based on an existing database. Os comandos são uma extensão para a plataforma cruzada dotnet comando, que é parte do SDK do .NET Core.The commands are an extension to the cross-platform dotnet command, which is part of the .NET Core SDK. Essas ferramentas funcionam com projetos do .NET Core.These tools work with .NET Core projects.

Se você estiver usando o Visual Studio, é recomendável o ferramentas do Console do Gerenciador de pacotes em vez disso:If you're using Visual Studio, we recommend the Package Manager Console tools instead:

  • Eles funcionam automaticamente com o projeto atual selecionado na Package Manager Console sem exigir que você mude manualmente os diretórios.They automatically work with the current project selected in the Package Manager Console without requiring that you manually switch directories.
  • Eles abrem automaticamente os arquivos gerados por um comando após a conclusão do comando.They automatically open files generated by a command after the command is completed.

Instalando as ferramentasInstalling the tools

O procedimento de instalação depende do tipo de projeto e de versão:The installation procedure depends on project type and version:

  • ASP.NET Core versão 2.1 e posteriorASP.NET Core version 2.1 and later
  • EF Core 2.xEF Core 2.x
  • EF Core 1.xEF Core 1.x

ASP.NET Core 2.1 +ASP.NET Core 2.1+

  • Instalar o atual SDK do .NET Core.Install the current .NET Core SDK. O SDK precisa ser instalado, mesmo se você tiver a versão mais recente do Visual Studio 2017.The SDK has to be installed even if you have the latest version of Visual Studio 2017.

    Isso é tudo o que é necessário para o ASP.NET Core 2.1 + porque o Microsoft.EntityFrameworkCore.Design pacote está incluído na metapacote Microsoft.This is all that is needed for ASP.NET Core 2.1+ because the Microsoft.EntityFrameworkCore.Design package is included in the Microsoft.AspNetCore.App metapackage.

EF Core 2.x (não no ASP.NET Core)EF Core 2.x (not ASP.NET Core)

O dotnet ef comandos forem incluídos no SDK do .NET Core, mas para habilitar os comandos que você precisa instalar o Microsoft.EntityFrameworkCore.Design pacote.The dotnet ef commands are included in the .NET Core SDK, but to enable the commands you have to install the Microsoft.EntityFrameworkCore.Design package.

  • Instalar o atual SDK do .NET Core.Install the current .NET Core SDK. O SDK precisa ser instalado, mesmo se você tiver a versão mais recente do Visual Studio 2017.The SDK has to be installed even if you have the latest version of Visual Studio 2017.

  • Instalar o estável mais recente Microsoft.EntityFrameworkCore.Design pacote.Install the latest stable Microsoft.EntityFrameworkCore.Design package.

    dotnet add package Microsoft.EntityFrameworkCore.Design
    

EF Core 1.xEF Core 1.x

  • Instale o .NET Core SDK versão 2.1.200.Install the .NET Core SDK version 2.1.200. Em versões posteriores não são compatíveis com as ferramentas CLI para o EF Core 1.0 e 1.1.Later versions are not compatible with CLI tools for EF Core 1.0 and 1.1.

  • Configurar o aplicativo para usar o 2.1.200 SDK versão modificando seus global. JSON arquivo.Configure the application to use the 2.1.200 SDK version by modifying its global.json file. Normalmente, esse arquivo está incluído no diretório da solução (um acima do projeto).This file is normally included in the solution directory (one above the project).

  • Edite o arquivo de projeto e adicione Microsoft.EntityFrameworkCore.Tools.DotNet como um DotNetCliToolReference item.Edit the project file and add Microsoft.EntityFrameworkCore.Tools.DotNet as a DotNetCliToolReference item. Especifique a versão mais recente do 1.x, por exemplo: 1.1.6.Specify the latest 1.x version, for example: 1.1.6. Consulte o exemplo de arquivo de projeto no final desta seção.See the project file example at the end of this section.

  • Instale a versão 1.x mais recente do Microsoft.EntityFrameworkCore.Design empacotar, por exemplo:Install the latest 1.x version of the Microsoft.EntityFrameworkCore.Design package, for example:

    dotnet add package Microsoft.EntityFrameworkCore.Design -v 1.1.6
    

    Com as duas referências de pacote adicionadas, o arquivo de projeto é semelhante a:With both package references added, the project file looks something like this:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp1.1</TargetFramework>
      </PropertyGroup>
      <ItemGroup>
        <PackageReference Include="Microsoft.EntityFrameworkCore.Design"
                          Version="1.1.6"
                           PrivateAssets="All" />
      </ItemGroup>
      <ItemGroup>
         <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
                                Version="1.1.6" />
      </ItemGroup>
    </Project>
    

    Uma referência de pacote com PrivateAssets="All" não é exposta aos projetos que fazem referência a este projeto.A package reference with PrivateAssets="All" isn't exposed to projects that reference this project. Essa restrição é especialmente útil para os pacotes que normalmente são usados apenas durante o desenvolvimento.This restriction is especially useful for packages that are typically only used during development.

Verificar a instalaçãoVerify installation

Execute os seguintes comandos para verificar se as ferramentas da CLI do EF Core estão corretamente instaladas:Run the following commands to verify that EF Core CLI tools are correctly installed:

dotnet restore
dotnet ef

A saída do comando identifica a versão das ferramentas do uso:The output from the command identifies the version of the tools in use:


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

Usando as ferramentasUsing the tools

Antes de usar as ferramentas, você talvez precise criar um projeto de inicialização ou defina o ambiente.Before using the tools, you might have to create a startup project or set the environment.

Projeto de destino e projeto de inicializaçãoTarget project and startup project

Os comandos se referir a um project e uma projeto de inicialização.The commands refer to a project and a startup project.

  • O project também é conhecido como o projeto de destino porque é onde os comandos Adicionar ou remover arquivos.The project is also known as the target project because it's where the commands add or remove files. Por padrão, o projeto no diretório atual é o projeto de destino.By default, the project in the current directory is the target project. Você pode especificar um projeto diferente como projeto de destino usando o --project opção.You can specify a different project as target project by using the --project option.

  • O projeto de inicialização é aquele que as ferramentas de compilar e executar.The startup project is the one that the tools build and run. Tem as ferramentas executar o código do aplicativo em tempo de design para obter informações sobre o projeto, como a cadeia de caracteres de conexão de banco de dados e a configuração do modelo.The tools have to execute application code at design time to get information about the project, such as the database connection string and the configuration of the model. Por padrão, o projeto no diretório atual é o projeto de inicialização.By default, the project in the current directory is the startup project. Você pode especificar um projeto diferente como projeto de inicialização usando o --startup-project opção.You can specify a different project as startup project by using the --startup-project option.

O projeto de inicialização e o projeto de destino geralmente são o mesmo projeto.The startup project and target project are often the same project. Um cenário típico no qual eles são projetos separados é que quando:A typical scenario where they are separate projects is when:

  • As classes de entidade e de contexto do EF Core estão em uma biblioteca de classes do .NET Core.The EF Core context and entity classes are in a .NET Core class library.
  • Um aplicativo de console .NET Core ou aplicativo web faz referência a biblioteca de classes.A .NET Core console app or web app references the class library.

Também é possível coloque o código de migrações em uma biblioteca de classes separada do contexto do EF Core.It's also possible to put migrations code in a class library separate from the EF Core context.

Outras estruturas de destinoOther target frameworks

As ferramentas da CLI funcionam com projetos do .NET Core e projetos do .NET Framework.The CLI tools work with .NET Core projects and .NET Framework projects. Os aplicativos que têm o modelo do EF Core em uma biblioteca de classes .NET Standard não podem ter um projeto de .NET Framework ou .NET Core.Apps that have the EF Core model in a .NET Standard class library might not have a .NET Core or .NET Framework project. Por exemplo, isso é verdadeiro para aplicativos Xamarin e plataforma Universal do Windows.For example, this is true of Xamarin and Universal Windows Platform apps. 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.In such cases, you can create a .NET Core console app project whose only purpose is to act as startup project for the tools. O projeto pode ser um projeto fictício, sem nenhum código real — só é necessário fornecer um destino para as ferramentas.The project can be a dummy project with no real code — it is only needed to provide a target for the tooling.

Por que é um projeto fictício necessário?Why is a dummy project required? Como mencionado anteriormente, as ferramentas de tem que executar o código do aplicativo em tempo de design.As mentioned earlier, the tools have to execute application code at design time. Para fazer isso, eles precisam usar o tempo de execução do .NET Core.To do that, they need to use the .NET Core runtime. Quando o modelo do EF Core está em um projeto que tem como alvo o .NET Core ou .NET Framework, as ferramentas do EF Core emprestam o tempo de execução do projeto.When the EF Core model is in a project that targets .NET Core or .NET Framework, the EF Core tools borrow the runtime from the project. E não é possível fazer isso se o modelo do EF Core está em uma biblioteca de classes .NET Standard.They can't do that if the EF Core model is in a .NET Standard class library. O .NET Standard não é uma implementação real do .NET; é uma especificação de um conjunto de APIs que devem dar suporte a implementações do .NET.The .NET Standard is not an actual .NET implementation; it's a specification of a set of APIs that .NET implementations must support. Portanto, .NET Standard não é suficiente para as ferramentas do EF Core executar o código do aplicativo.Therefore .NET Standard is not sufficient for the EF Core tools to execute application code. 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.The dummy project you create to use as startup project provides a concrete target platform into which the tools can load the .NET Standard class library.

Ambiente do ASP.NET CoreASP.NET Core environment

Para especificar o ambiente para projetos do ASP.NET Core, defina as ASPNETCORE_ENVIRONMENT variável de ambiente antes de executar comandos.To specify the environment for ASP.NET Core projects, set the ASPNETCORE_ENVIRONMENT environment variable before running commands.

Opções comunsCommon options

OpçãoOption DescriçãoDescription
--json Mostra a saída JSON.Show JSON output.
-c --context <DBCONTEXT> O DbContext classe a ser usada.The DbContext class to use. Nome de classe totalmente qualificado com namespaces ou única.Class name only or fully qualified with namespaces. Se essa opção for omitida, o EF Core encontrará a classe de contexto.If this option is omitted, EF Core will find the context class. Se houver várias classes de contexto, essa opção é necessária.If there are multiple context classes, this option is required.
-p --project <PROJECT> Caminho relativo à pasta do projeto do projeto de destino.Relative path to the project folder of the target project. Valor padrão é a pasta atual.Default value is the current folder.
-s --startup-project <PROJECT> Caminho relativo à pasta do projeto do projeto de inicialização.Relative path to the project folder of the startup project. Valor padrão é a pasta atual.Default value is the current folder.
--framework <FRAMEWORK> O Moniker da estrutura de destino para o estrutura de destino.The Target Framework Moniker for the target framework. Use quando o arquivo de projeto especifica várias estruturas de destino, e você deseja selecionar um deles.Use when the project file specifies multiple target frameworks, and you want to select one of them.
--configuration <CONFIGURATION> A configuração de build, por exemplo: Debug ou Release.The build configuration, for example: Debug or Release.
--runtime <IDENTIFIER> O identificador do tempo de execução para restaurar os pacotes para o destino.The identifier of the target runtime to restore packages for. Para obter uma lista de RIDs (Identificadores de Tempo de Execução), veja o Catálogo de RIDs.For a list of Runtime Identifiers (RIDs), see the RID catalog.
-h --help Mostre informações de Ajuda.Show help information.
-v --verbose Mostra saída detalhada.Show verbose output.
--no-color Não colorir saída.Don't colorize output.
--prefix-output Prefixo com o nível de saída.Prefix output with level.

lista de banco de dados do dotnet efdotnet ef database drop

Descarta o banco de dados.Drops the database.

Opções:Options:

OpçãoOption DescriçãoDescription
-f --force Confirme se não.Don't confirm.
--dry-run Mostrar qual banco de dados deve ser descartado, mas não o remova.Show which database would be dropped, but don't drop it.

atualização de banco de dados do dotnet efdotnet ef database update

Atualiza o banco de dados para a última migração ou para uma migração especificada.Updates the database to the last migration or to a specified migration.

Argumentos:Arguments:

ArgumentoArgument DescriçãoDescription
<MIGRATION> A migração de destino.The target migration. As migrações podem ser identificadas por nome ou ID.Migrations may be identified by name or by ID. O número de 0 é um caso especial que significa antes da primeira migração e faz com que todas as migrações para ser revertido.The number 0 is a special case that means before the first migration and causes all migrations to be reverted. Se nenhuma migração for especificada, o comando assume como padrão para a última migração.If no migration is specified, the command defaults to the last migration.

Os exemplos a seguir atualiza o banco de dados para uma migração especificada.The following examples update the database to a specified migration. O primeiro usa o nome da migração e o segundo usa a ID de migração:The first uses the migration name and the second uses the migration ID:

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate

informações do dotnet ef dbcontextdotnet ef dbcontext info

Obtém informações sobre um DbContext tipo.Gets information about a DbContext type.

lista do dotnet ef dbcontextdotnet ef dbcontext list

Listas disponíveis DbContext tipos.Lists available DbContext types.

scaffold do dotnet ef dbcontextdotnet ef dbcontext scaffold

Gera código para um DbContext e tipos de entidade para um banco de dados.Generates code for a DbContext and entity types for a database. Para este comando para gerar um tipo de entidade que, a tabela de banco de dados deve ter uma chave primária.In order for this command to generate an entity type, the database table must have a primary key.

Argumentos:Arguments:

ArgumentoArgument DescriçãoDescription
<CONNECTION> A cadeia de conexão para o banco de dados.The connection string to the database. Para projetos do ASP.NET Core 2.x, o valor pode ser nome =<nome da cadeia de caracteres de conexão >.For ASP.NET Core 2.x projects, the value can be name=<name of connection string>. Nesse caso, o nome vem de fontes de configuração que são configuradas para o projeto.In that case the name comes from the configuration sources that are set up for the project.
<PROVIDER> O provedor a ser usado.The provider to use. Normalmente isso é o nome do pacote do NuGet, por exemplo: Microsoft.EntityFrameworkCore.SqlServer.Typically this is the name of the NuGet package, for example: Microsoft.EntityFrameworkCore.SqlServer.

Opções:Options:

OpçãoOption DescriçãoDescription
-d-d --data-annotations Use atributos para configurar o modelo (quando possível).Use attributes to configure the model (where possible). Se essa opção for omitida, somente a API fluente é usada.If this option is omitted, only the fluent API is used.
-c --context <NAME> O nome da DbContext classe gerar.The name of the DbContext class to generate.
--context-dir <PATH> O diretório para colocar o DbContext arquivo de classe no.The directory to put the DbContext class file in. Caminhos são relativos ao diretório do projeto.Paths are relative to the project directory. Namespaces são derivados dos nomes de pasta.Namespaces are derived from the folder names.
-f --force Substitua arquivos existentes.Overwrite existing files.
-o --output-dir <PATH> O diretório para colocar os arquivos de classe de entidade.The directory to put entity class files in. Caminhos são relativos ao diretório do projeto.Paths are relative to the project directory.
--schema <SCHEMA_NAME>... Os esquemas de tabelas para gerar tipos de entidade para.The schemas of tables to generate entity types for. Para especificar vários esquemas, repita --schema para cada uma delas.To specify multiple schemas, repeat --schema for each one. Se essa opção for omitida, todos os esquemas são incluídos.If this option is omitted, all schemas are included.
-t --table <TABLE_NAME>...--table <TABLE_NAME>... As tabelas para gerar tipos de entidade para.The tables to generate entity types for. Para especificar várias tabelas, repita -t ou --table para cada uma delas.To specify multiple tables, repeat -t or --table for each one. Se essa opção for omitida, todas as tabelas são incluídas.If this option is omitted, all tables are included.
--use-database-names Use nomes de tabela e coluna exatamente como aparecem no banco de dados.Use table and column names exactly as they appear in the database. Se essa opção for omitida, nomes de banco de dados são alterados de acordo com mais de perto para convenções de estilo de nome em C#.If this option is omitted, database names are changed to more closely conform to C# name style conventions.

O exemplo a seguir usa o Scaffold de todos os esquemas e tabelas e coloca os novos arquivos na modelos pasta.The following example scaffolds all schemas and tables and puts the new files in the Models folder.

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

O exemplo a seguir usa o Scaffold somente tabelas selecionadas e cria o contexto em uma pasta separada com um nome especificado:The following example scaffolds only selected tables and creates the context in a separate folder with a specified name:

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

Adicionar migrações do ef dotnetdotnet ef migrations add

Adiciona uma nova migração.Adds a new migration.

Argumentos:Arguments:

ArgumentoArgument DescriçãoDescription
<NAME> O nome da migração.The name of the migration.

Opções:Options:

OpçãoOption DescriçãoDescription
-o --output-dir <PATH> O diretório (e sub-namespace) para usar.The directory (and sub-namespace) to use. Caminhos são relativos ao diretório do projeto.Paths are relative to the project directory. O padrão é "Migrações".Defaults to "Migrations".

lista de migrações dotnet efdotnet ef migrations list

Lista as migrações disponíveis.Lists available migrations.

Remover de migrações do ef dotnetdotnet ef migrations remove

Remove a última migração (reverte as alterações de código que foram feitas para a migração).Removes the last migration (rolls back the code changes that were done for the migration).

Opções:Options:

OpçãoOption DescriçãoDescription
-f --force Reverter a migração (reverter as alterações que foram aplicadas ao banco de dados).Revert the migration (roll back the changes that were applied to the database).

script de migrações dotnet efdotnet ef migrations script

Gera um script SQL de migrações.Generates a SQL script from migrations.

Argumentos:Arguments:

ArgumentoArgument DescriçãoDescription
<FROM> A migração inicial.The starting migration. As migrações podem ser identificadas por nome ou ID.Migrations may be identified by name or by ID. O número de 0 é um caso especial que significa antes da primeira migração.The number 0 is a special case that means before the first migration. O padrão é 0.Defaults to 0.
<TO> A migração final.The ending migration. O padrão é para a última migração.Defaults to the last migration.

Opções:Options:

OpçãoOption DescriçãoDescription
-o --output <FILE> O arquivo para gravar o script.The file to write the script to.
-i --idempotent Gere um script que pode ser usado em um banco de dados em qualquer migração.Generate a script that can be used on a database at any migration.

O exemplo a seguir cria um script para a migração de InitialCreate:The following example creates a script for the InitialCreate migration:

dotnet ef migrations script 0 InitialCreate

O exemplo a seguir cria um script para todas as migrações após a migração InitialCreate.The following example creates a script for all migrations after the InitialCreate migration.

dotnet ef migrations script 20180904195021_InitialCreate

Recursos adicionaisAdditional resources