Referência de ferramentas de Entity Framework Core – console do Gerenciador de pacotes no Visual StudioEntity Framework Core tools reference - Package Manager Console in Visual Studio

As ferramentas do console do Gerenciador de pacotes (PMC) para Entity Framework Core executam tarefas de desenvolvimento em tempo de design.The Package Manager Console (PMC) tools for Entity Framework Core perform design-time development tasks. Por exemplo, eles criam migrações, aplicam migrações e geram 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 executados dentro do Visual Studio usando o console do Gerenciador de pacotes.The commands run inside of Visual Studio using the Package Manager Console. Essas ferramentas funcionam com projetos do .NET Framework e o do .NET Core.These tools work with both .NET Framework and .NET Core projects.

Se você não estiver usando o Visual Studio, recomendamos o EF Core ferramentas de linha de comando .If you aren't using Visual Studio, we recommend the EF Core Command-line Tools instead. As ferramentas de CLI do .NET Core são entre plataformas e são executadas dentro de um prompt de comando.The .NET Core CLI tools are cross-platform and run inside a command prompt.

Instalando as ferramentasInstalling the tools

Os procedimentos para instalar e atualizar as ferramentas diferem entre ASP.NET Core 2.1 + e versões anteriores ou outros tipos de projeto.The procedures for installing and updating the tools differ between ASP.NET Core 2.1+ and earlier versions or other project types.

ASP.NET Core versão 2,1 e posteriorASP.NET Core version 2.1 and later

As ferramentas são incluídas automaticamente em um projeto ASP.NET Core 2.1 + porque o Microsoft.EntityFrameworkCore.Tools pacote está incluído no metapacote Microsoft. AspNetCore. app.The tools are automatically included in an ASP.NET Core 2.1+ project because the Microsoft.EntityFrameworkCore.Tools package is included in the Microsoft.AspNetCore.App metapackage.

Portanto, você não precisa fazer nada para instalar as ferramentas, mas é necessário:Therefore, you don't have to do anything to install the tools, but you do have to:

  • Restaure os pacotes antes de usar as ferramentas em um novo projeto.Restore packages before using the tools in a new project.
  • Instale um pacote para atualizar as ferramentas para uma versão mais recente.Install a package to update the tools to a newer version.

Para certificar-se de que você está obtendo a versão mais recente das ferramentas, recomendamos que você também faça a seguinte etapa:To make sure that you're getting the latest version of the tools, we recommend that you also do the following step:

  • Edite seu arquivo . csproj e adicione uma linha especificando a versão mais recente do pacote Microsoft. EntityFrameworkCore. Tools .Edit your .csproj file and add a line specifying the latest version of the Microsoft.EntityFrameworkCore.Tools package. Por exemplo, o arquivo . csproj pode incluir um ItemGroup que se parece com o seguinte:For example, the .csproj file might include an ItemGroup that looks like this:

    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.App" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.1.3" />
      <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="3.1.2" />
    </ItemGroup>
    

Atualize as ferramentas quando receber uma mensagem semelhante ao exemplo a seguir:Update the tools when you get a message like the following example:

A versão de ferramentas de EF Core ' 2.1.1-RTM-30846 ' é mais antiga que a do tempo de execução ' 2.1.3-RTM-32065 '.The EF Core tools version '2.1.1-rtm-30846' is older than that of the runtime '2.1.3-rtm-32065'. Atualize as ferramentas para os recursos e correções de bug mais recentes.Update the tools for the latest features and bug fixes.

Para atualizar as ferramentas:To update the tools:

  • instale o SDK do .NET Core mais recente.Install the latest .NET Core SDK.
  • Atualize o Visual Studio para a última versão.Update Visual Studio to the latest version.
  • Edite o arquivo . csproj para que ele inclua uma referência de pacote para o pacote de ferramentas mais recente, conforme mostrado anteriormente.Edit the .csproj file so that it includes a package reference to the latest tools package, as shown earlier.

Outras versões e tipos de projetoOther versions and project types

Instale as ferramentas do console do Gerenciador de pacotes executando o seguinte comando no console do Gerenciador de pacotes:Install the Package Manager Console tools by running the following command in Package Manager Console:

Install-Package Microsoft.EntityFrameworkCore.Tools

Atualize as ferramentas executando o comando a seguir no console do Gerenciador de pacotes.Update the tools by running the following command in Package Manager Console.

Update-Package Microsoft.EntityFrameworkCore.Tools

Verificar a instalaçãoVerify the installation

Verifique se as ferramentas estão instaladas executando este comando:Verify that the tools are installed by running this command:

Get-Help about_EntityFrameworkCore

A saída é parecida com esta (não informa qual versão das ferramentas você está usando):The output looks like this (it doesn't tell you which version of the tools you're using):


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

TOPIC
    about_EntityFrameworkCore

SHORT DESCRIPTION
    Provides information about the Entity Framework Core Package Manager Console Tools.

<A list of available commands follows, omitted here.>

Usando as ferramentasUsing the tools

Antes de usar as ferramentas:Before using the tools:

  • Entenda a diferença entre o destino e o projeto de inicialização.Understand the difference between target and startup project.
  • Saiba como usar as ferramentas com .NET Standard bibliotecas de classe.Learn how to use the tools with .NET Standard class libraries.
  • Para projetos ASP.NET Core, defina o ambiente.For ASP.NET Core projects, set the environment.

Projeto de destino e inicializaçãoTarget and startup project

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

  • O projeto também é conhecido como o projeto de destino porque é onde os comandos adicionam ou removem 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 padrão selecionado no console do Gerenciador de pacotes é o projeto de destino.By default, the Default project selected in Package Manager Console is the target project. Você pode especificar um projeto diferente como projeto de destino usando a --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 criam e executam.The startup project is the one that the tools build and run. 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.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 de inicialização no Gerenciador de soluções é o projeto de inicialização.By default, the Startup Project in Solution Explorer is the startup project. Você pode especificar um projeto diferente como projeto de inicialização usando a --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 em que são projetos separados é quando:A typical scenario where they are separate projects is when:

  • O contexto de EF Core e as classes de entidade 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 do .NET Core ou aplicativo Web faz referência à biblioteca de classes.A .NET Core console app or web app references the class library.

Também é possível colocar o código de migrações em uma biblioteca de classes separada do contexto de 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 de console do Gerenciador de pacotes funcionam com projetos .NET Core ou .NET Framework.The Package Manager Console tools work with .NET Core or .NET Framework projects. 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.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 do .NET Core ou .NET Framework, cujo único propósito é agir como projeto de inicialização para as ferramentas.In such cases, you can create a .NET Core or .NET Framework console app project whose only purpose is to act as startup project for the tools. O projeto pode ser um projeto fictício sem código real — , ele só é necessário para 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? Conforme mencionado anteriormente, as ferramentas precisam 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 .NET Core ou o .NET Framework Runtime.To do that, they need to use the .NET Core or .NET Framework runtime. 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.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. Eles não poderão fazer isso se o modelo de EF Core estiver 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 para as quais as implementações do .NET devem dar suporte.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 de EF Core executarem 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 o .NET Standard biblioteca de classes.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 de ASP.NET CoreASP.NET Core environment

Para especificar o ambiente para projetos de ASP.NET Core, defina env: ASPNETCORE_ENVIRONMENT antes de executar os comandos.To specify the environment for ASP.NET Core projects, set env:ASPNETCORE_ENVIRONMENT before running commands.

Parâmetros comunsCommon parameters

A tabela a seguir mostra os parâmetros que são comuns a todos os comandos de EF Core:The following table shows parameters that are common to all of the EF Core commands:

ParâmetroParameter DescriçãoDescription
-Contexto<String>-Context <String> A classe DbContext a ser usada.The DbContext class to use. Nome da classe somente ou totalmente qualificado com namespaces.Class name only or fully qualified with namespaces. Se esse parâmetro for omitido, EF Core encontrará a classe de contexto.If this parameter is omitted, EF Core finds the context class. Se houver várias classes de contexto, esse parâmetro será necessário.If there are multiple context classes, this parameter is required.
-Projeto<String>-Project <String> O projeto de destino.The target project. Se esse parâmetro for omitido, o projeto padrão do console do Gerenciador de pacotes será usado como o projeto de destino.If this parameter is omitted, the Default project for Package Manager Console is used as the target project.
-StartupProject<String>-StartupProject <String> O projeto de inicialização.The startup project. Se esse parâmetro for omitido, o projeto de inicialização nas propriedades da solução será usado como o projeto de destino.If this parameter is omitted, the Startup project in Solution properties is used as the target project.
-Verbose-Verbose Mostrar saída detalhada.Show verbose output.

Para mostrar informações de ajuda sobre um comando, use o Get-Help comando do PowerShell.To show help information about a command, use PowerShell's Get-Help command.

Dica

Os parâmetros Context, Project e StartupProject dão suporte à expansão de tabulação.The Context, Project, and StartupProject parameters support tab-expansion.

Adicionar e migrarAdd-Migration

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

Parâmetros:Parameters:

ParâmetroParameter DescriçãoDescription
-Nome<String>-Name <String> O nome da migração.The name of the migration. Esse é um parâmetro posicional e é necessário.This is a positional parameter and is required.
-OutputDir<String>-OutputDir <String> O diretório é usado para gerar os arquivos.The directory use to output the files. Os caminhos são relativos ao diretório do projeto de destino.Paths are relative to the target project directory. O padrão é "migrações".Defaults to "Migrations".
-Namespace<String>-Namespace <String> O namespace a ser usado para as classes geradas.The namespace to use for the generated classes. O padrão é gerado a partir do diretório de saída.Defaults to generated from the output directory. (Disponível em EFCore 5.0.0 em diante.)(Available from EFCore 5.0.0 onwards.)

Remover banco de dadosDrop-Database

Remove o banco de dados.Drops the database.

Parâmetros:Parameters:

ParâmetroParameter DescriçãoDescription
-WhatIf-WhatIf Mostrar qual banco de dados seria descartado, mas não descartá-lo.Show which database would be dropped, but don't drop it.

Get-DbContextGet-DbContext

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

Remove-MigrationRemove-Migration

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

Parâmetros:Parameters:

ParâmetroParameter DescriçãoDescription
-Force-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).

Scaffold-DbContextScaffold-DbContext

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

Parâmetros:Parameters:

ParâmetroParameter DescriçãoDescription
-Conexão<String>-Connection <String> A cadeia de conexão para o banco de dados.The connection string to the database. Para projetos ASP.NET Core 2. x, o valor pode ser *nome = <name of connection string> *.For ASP.NET Core 2.x projects, the value can be name=<name of connection string>. Nesse caso, o nome é proveniente das fontes de configuração que estão configuradas para o projeto.In that case the name comes from the configuration sources that are set up for the project. Esse é um parâmetro posicional e é necessário.This is a positional parameter and is required.
-Provedor<String>-Provider <String> O provedor a ser usado.The provider to use. Normalmente, esse é o nome do pacote NuGet, por exemplo: Microsoft.EntityFrameworkCore.SqlServer .Typically this is the name of the NuGet package, for example: Microsoft.EntityFrameworkCore.SqlServer. Esse é um parâmetro posicional e é necessário.This is a positional parameter and is required.
-OutputDir<String>-OutputDir <String> O diretório no qual colocar arquivos.The directory to put files in. Os caminhos são relativos ao diretório do projeto.Paths are relative to the project directory.
-ContextDir<String>-ContextDir <String> O diretório no qual colocar o DbContext arquivo.The directory to put the DbContext file in. Os caminhos são relativos ao diretório do projeto.Paths are relative to the project directory.
-Namespace<String>-Namespace <String> O namespace a ser usado para todas as classes geradas.The namespace to use for all generated classes. O padrão é gerado a partir do namespace raiz e do diretório de saída.Defaults to generated from the root namespace and the output directory. (Disponível em EFCore 5.0.0 em diante.)(Available from EFCore 5.0.0 onwards.)
-ContextNamespace<String>-ContextNamespace <String> O namespace a ser usado para a DbContext classe gerada.The namespace to use for the generated DbContext class. Observação: substituições -Namespace .Note: overrides -Namespace. (Disponível em EFCore 5.0.0 em diante.)(Available from EFCore 5.0.0 onwards.)
-Contexto<String>-Context <String> O nome da DbContext classe a ser gerada.The name of the DbContext class to generate.
-Esquemas<String[]>-Schemas <String[]> Os esquemas de tabelas para os quais gerar tipos de entidade.The schemas of tables to generate entity types for. Se esse parâmetro for omitido, todos os esquemas serão incluídos.If this parameter is omitted, all schemas are included.
-Tabelas<String[]>-Tables <String[]> As tabelas para as quais gerar tipos de entidade.The tables to generate entity types for. Se esse parâmetro for omitido, todas as tabelas serão incluídas.If this parameter is omitted, all tables are included.
-Annotations-DataAnnotations Use atributos para configurar o modelo (sempre que possível).Use attributes to configure the model (where possible). Se esse parâmetro for omitido, somente a API fluente será usada.If this parameter is omitted, only the fluent API is used.
-UseDatabaseNames-UseDatabaseNames 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 esse parâmetro for omitido, os nomes de banco de dados serão alterados para se adequar melhor às convenções de estilo de nome C#.If this parameter is omitted, database names are changed to more closely conform to C# name style conventions.
-Force-Force Substitui os arquivos existentes.Overwrite existing files.
-NoOnConfiguring-NoOnConfiguring Suprime a geração do OnConfiguring método na classe gerada DbContext .Suppresses generation of the OnConfiguring method in the generated DbContext class. (Disponível em EFCore 5.0.0 em diante.)(Available from EFCore 5.0.0 onwards.)

Exemplo:Example:

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

Exemplo que aplica Scaffold apenas tabelas selecionadas e cria o contexto em uma pasta separada com um nome e namespace especificados:Example that scaffolds only selected tables and creates the context in a separate folder with a specified name and namespace:

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models -Tables "Blog","Post" -ContextDir Context -Context BlogContext -ContextNamespace New.Namespace

Script – migraçãoScript-Migration

Gera um script SQL que aplica todas as alterações de uma migração selecionada para outra migração selecionada.Generates a SQL script that applies all of the changes from one selected migration to another selected migration.

Parâmetros:Parameters:

ParâmetroParameter DescriçãoDescription
-De<String>-From <String> A migração inicial.The starting migration. As migrações podem ser identificadas por nome ou por ID.Migrations may be identified by name or by ID. O número 0 é um caso especial que significa antes da primeira migração.The number 0 is a special case that means before the first migration. Assume o padrão de 0.Defaults to 0.
-Para<String>-To <String> A migração final.The ending migration. O padrão é a última migração.Defaults to the last migration.
-Idempotente-Idempotent Gere um script que possa ser usado em um banco de dados em qualquer migração.Generate a script that can be used on a database at any migration.
-Saída<String>-Output <String> O arquivo no qual o resultado será gravado.The file to write the result to. Se esse parâmetro for omitido, o arquivo será criado com um nome gerado na mesma pasta que os arquivos de tempo de execução do aplicativo são criados, por exemplo: /obj/Debug/netcoreapp2.1/ghbkztfz.SQL/.IF this parameter is omitted, the file is created with a generated name in the same folder as the app's runtime files are created, for example: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Dica

Os parâmetros para, de e saída dão suporte à expansão de tabulação.The To, From, and Output parameters support tab-expansion.

O exemplo a seguir cria um script para a migração InitialCreate, usando o nome de migração.The following example creates a script for the InitialCreate migration, using the migration name.

Script-Migration -To InitialCreate

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

Script-Migration -From 20180904195021_InitialCreate

Atualizar banco de dadosUpdate-Database

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.

ParâmetroParameter DescriçãoDescription
-Migração<String>-Migration <String> A migração de destino.The target migration. As migrações podem ser identificadas por nome ou por ID.Migrations may be identified by name or by 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.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 usa como padrão a última migração.If no migration is specified, the command defaults to the last migration.
-Conexão<String>-Connection <String> A cadeia de conexão para o banco de dados.The connection string to the database. O padrão é aquele especificado em AddDbContext ou OnConfiguring .Defaults to the one specified in AddDbContext or OnConfiguring.

Dica

O parâmetro de migração oferece suporte à expansão de tabulação.The Migration parameter supports tab-expansion.

O exemplo a seguir reverte todas as migrações.The following example reverts all migrations.

Update-Database -Migration 0

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

Update-Database -Migration InitialCreate
Update-Database -Migration 20180904195021_InitialCreate -Connection your_connection_string

Recursos adicionaisAdditional resources