ASP.NET Core MVC com EF Core – migrações – 4 de 10ASP.NET Core MVC with EF Core - Migrations - 4 of 10

Este tutorial não foi atualizado para o ASP.NET Core 2.1.This tutorial has not been upgraded to ASP.NET Core 2.1. A versão deste tutorial para o ASP.NET Core 2.0 pode ser consultada selecionando ASP.NET Core 2.0 acima do sumário ou na parte superior da página:The ASP.NET Core 2.0 version of this tutorial is available by selecting ASP.NET Core 2.0 above the table of contents or at the top of the page:

A versão deste tutorial do Razor Pages para o ASP.NET Core 2.1 conta com várias melhorias em relação à versão 2.0.The ASP.NET Core 2.1 Razor Pages version of this tutorial has many improvements over the 2.0 version.

O tutorial do 2.0 ensina a usar o ASP.NET Core MVC e o Entity Framework Core com controladores e exibições.The 2.0 tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. O Razor Pages é um modelo de programação baseado em página que torna a criação da interface do usuário da Web mais fácil e produtiva.Razor Pages is a page-based programming model that makes building web UI easier and more productive. É recomendável tentar o tutorial das Páginas Razor na versão do MVC.We recommend the Razor Pages tutorial over the MVC version. O tutorial Páginas do Razor:The Razor Pages tutorial:

  • É mais fácil de acompanhar.Is easier to follow. Por exemplo, o código de scaffolding foi bastante simplificado.For example, the scaffolding code has been significantly simplified.
  • Fornece mais práticas recomendadas do EF Core.Provides more EF Core best practices.
  • Usa consultas mais eficientes.Uses more efficient queries.
  • É mais atual com a API mais recente.Is more current with the latest API.
  • Aborda mais recursos.Covers more features.
  • É a abordagem preferencial para o desenvolvimento de novos aplicativos.Is the preferred approach for new application development.

Se você escolher este tutorial em vez da versão Razor Pages, deixe uma observação explicando o motivo nesta discussão do GitHub.If you choose this tutorial over the Razor Pages version, let us know why in this GitHub discussion.

Por Tom Dykstra e Rick AndersonBy Tom Dykstra and Rick Anderson

O aplicativo web de exemplo Contoso University demonstra como criar aplicativos web do ASP.NET Core MVC usando o Entity Framework Core e o Visual Studio.The Contoso University sample web application demonstrates how to create ASP.NET Core MVC web applications using Entity Framework Core and Visual Studio. Para obter informações sobre a série de tutoriais, consulte o primeiro tutorial da série.For information about the tutorial series, see the first tutorial in the series.

Neste tutorial, você começa usando o recurso de migrações do EF Core para o gerenciamento de alterações do modelo de dados.In this tutorial, you start using the EF Core migrations feature for managing data model changes. Em tutoriais seguintes, você adicionará mais migrações conforme você alterar o modelo de dados.In later tutorials, you'll add more migrations as you change the data model.

Introdução às migraçõesIntroduction to migrations

Quando você desenvolve um novo aplicativo, o modelo de dados é alterado com frequência e, sempre que o modelo é alterado, ele fica fora de sincronia com o banco de dados.When you develop a new application, your data model changes frequently, and each time the model changes, it gets out of sync with the database. Você começou estes tutoriais configurando o Entity Framework para criar o banco de dados, caso ele não exista.You started these tutorials by configuring the Entity Framework to create the database if it doesn't exist. Em seguida, sempre que você alterar o modelo de dados – adicionar, remover, alterar classes de entidade ou alterar a classe DbContext –, poderá excluir o banco de dados e o EF criará um novo que corresponde ao modelo e o propagará com os dados de teste.Then each time you change the data model -- add, remove, or change entity classes or change your DbContext class -- you can delete the database and EF creates a new one that matches the model, and seeds it with test data.

Esse método de manter o banco de dados em sincronia com o modelo de dados funciona bem até que você implante o aplicativo em produção.This method of keeping the database in sync with the data model works well until you deploy the application to production. Quando o aplicativo é executado em produção, ele normalmente armazena os dados que você deseja manter, e você não quer perder tudo sempre que fizer uma alteração, como a adição de uma nova coluna.When the application is running in production it's usually storing data that you want to keep, and you don't want to lose everything each time you make a change such as adding a new column. O recurso Migrações do EF Core resolve esse problema, permitindo que o EF atualize o esquema de banco de dados em vez de criar um novo banco de dados.The EF Core Migrations feature solves this problem by enabling EF to update the database schema instead of creating a new database.

Pacotes NuGet do Entity Framework Core para migraçõesEntity Framework Core NuGet packages for migrations

Para trabalhar com migrações, use o PMC (Console do Gerenciador de Pacotes) ou a CLI (interface de linha de comando).To work with migrations, you can use the Package Manager Console (PMC) or the command-line interface (CLI). Esses tutoriais mostram como usar comandos da CLI.These tutorials show how to use CLI commands. Encontre informações sobre o PMC no final deste tutorial.Information about the PMC is at the end of this tutorial.

As ferramentas do EF para a CLI (interface de linha de comando) são fornecidas em Microsoft.EntityFrameworkCore.Tools.DotNet.The EF tools for the command-line interface (CLI) are provided in Microsoft.EntityFrameworkCore.Tools.DotNet. Para instalar esse pacote, adicione-o à coleção DotNetCliToolReference no arquivo .csproj, conforme mostrado.To install this package, add it to the DotNetCliToolReference collection in the .csproj file, as shown. Observação: é necessário instalar este pacote editando o arquivo .csproj; não é possível usar o comando install-package ou a GUI do Gerenciador de Pacotes.Note: You have to install this package by editing the .csproj file; you can't use the install-package command or the package manager GUI. Edite o arquivo .csproj clicando com o botão direito do mouse no nome do projeto no Gerenciador de Soluções e selecionando Editar ContosoUniversity.csproj.You can edit the .csproj file by right-clicking the project name in Solution Explorer and selecting Edit ContosoUniversity.csproj.

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

(Neste exemplo, os números de versão eram atuais no momento em que o tutorial foi escrito.)(The version numbers in this example were current when the tutorial was written.)

Alterar a cadeia de conexãoChange the connection string

No arquivo appsettings.json, altere o nome do banco de dados na cadeia de conexão para ContosoUniversity2 ou outro nome que você ainda não usou no computador que está sendo usado.In the appsettings.json file, change the name of the database in the connection string to ContosoUniversity2 or some other name that you haven't used on the computer you're using.

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=ContosoUniversity2;Trusted_Connection=True;MultipleActiveResultSets=true"
  },

Essa alteração configura o projeto, de modo que a primeira migração crie um novo banco de dados.This change sets up the project so that the first migration will create a new database. Isso não é necessário para começar as migrações, mas você verá mais tarde o motivo pelo qual essa é uma boa ideia.This isn't required to get started with migrations, but you'll see later why it's a good idea.

Observação

Como alternativa à alteração do nome do banco de dados, você pode excluir o banco de dados.As an alternative to changing the database name, you can delete the database. Use o SSOX (Pesquisador de Objetos do SQL Server) ou o comando database drop da CLI:Use SQL Server Object Explorer (SSOX) or the database drop CLI command:

dotnet ef database drop

A seção a seguir explica como executar comandos da CLI.The following section explains how to run CLI commands.

Criar uma migração inicialCreate an initial migration

Salve as alterações e compile o projeto.Save your changes and build the project. Em seguida, abra uma janela Comando e navegue para a pasta do projeto.Then open a command window and navigate to the project folder. Esta é uma maneira rápida de fazer isso:Here's a quick way to do that:

  • No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e escolha Abrir no Explorador de Arquivos no menu de contexto.In Solution Explorer, right-click the project and choose Open in File Explorer from the context menu.

    Abrir no item de menu do Explorador de Arquivos

  • Insira "cmd" na barra de endereços e pressione Enter.Enter "cmd" in the address bar and press Enter.

    Abrir a janela Comando

Insira o seguinte comando na janela de comando:Enter the following command in the command window:

dotnet ef migrations add InitialCreate

Você verá uma saída semelhante à seguinte na janela Comando:You see output like the following in the command window:

info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
      User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
      Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider 'Microsoft.EntityFrameworkCore.SqlServer' with options: None
Done. To undo this action, use 'ef migrations remove'

Observação

Se você receber uma mensagem de erro Nenhum comando "dotnet-ef" executável correspondente encontrado, consulte esta postagem no blog para ajudar a solucionar o problema.If you see an error message No executable found matching command "dotnet-ef", see this blog post for help troubleshooting.

Se você receber uma mensagem de erro "Não é possível acessar o arquivo... ContosoUniversity.dll porque ele está sendo usado por outro processo", localize o ícone do IIS Express na Bandeja do Sistema do Windows, clique com o botão direito do mouse nele e, em seguida, clique em ContosoUniversity > Parar Site.If you see an error message "cannot access the file ... ContosoUniversity.dll because it is being used by another process.", find the IIS Express icon in the Windows System Tray, and right-click it, then click ContosoUniversity > Stop Site.

Examinar os métodos Up e DownExamine the Up and Down methods

Quando você executou o comando migrations add, o EF gerou o código que criará o banco de dados do zero.When you executed the migrations add command, EF generated the code that will create the database from scratch. Esse código está localizado na pasta Migrations, no arquivo chamado <timestamp>_InitialCreate.cs.This code is in the Migrations folder, in the file named <timestamp>_InitialCreate.cs. O método Up da classe InitialCreate cria as tabelas de banco de dados que correspondem aos conjuntos de entidades do modelo de dados, e o método Down exclui-as, conforme mostrado no exemplo a seguir.The Up method of the InitialCreate class creates the database tables that correspond to the data model entity sets, and the Down method deletes them, as shown in the following example.

public partial class InitialCreate : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.CreateTable(
            name: "Course",
            columns: table => new
            {
                CourseID = table.Column<int>(nullable: false),
                Credits = table.Column<int>(nullable: false),
                Title = table.Column<string>(nullable: true)
            },
            constraints: table =>
            {
                table.PrimaryKey("PK_Course", x => x.CourseID);
            });

        // Additional code not shown
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropTable(
            name: "Enrollment");
        // Additional code not shown
    }
}

As migrações chamam o método Up para implementar as alterações do modelo de dados para uma migração.Migrations calls the Up method to implement the data model changes for a migration. Quando você insere um comando para reverter a atualização, as Migrações chamam o método Down.When you enter a command to roll back the update, Migrations calls the Down method.

Esse código destina-se à migração inicial que foi criada quando você inseriu o comando migrations add InitialCreate.This code is for the initial migration that was created when you entered the migrations add InitialCreate command. O parâmetro de nome da migração ("InitialCreate" no exemplo) é usado para o nome do arquivo e pode ser o que você desejar.The migration name parameter ("InitialCreate" in the example) is used for the file name and can be whatever you want. É melhor escolher uma palavra ou frase que resume o que está sendo feito na migração.It's best to choose a word or phrase that summarizes what is being done in the migration. Por exemplo, você pode nomear uma migração posterior "AddDepartmentTable".For example, you might name a later migration "AddDepartmentTable".

Se você criou a migração inicial quando o banco de dados já existia, o código de criação de banco de dados é gerado, mas ele não precisa ser executado porque o banco de dados já corresponde ao modelo de dados.If you created the initial migration when the database already exists, the database creation code is generated but it doesn't have to run because the database already matches the data model. Quando você implantar o aplicativo em outro ambiente no qual o banco de dados ainda não existe, esse código será executado para criar o banco de dados; portanto, é uma boa ideia testá-lo primeiro.When you deploy the app to another environment where the database doesn't exist yet, this code will run to create your database, so it's a good idea to test it first. É por isso que você alterou o nome do banco de dados na cadeia de conexão anteriormente – para que as migrações possam criar um novo do zero.That's why you changed the name of the database in the connection string earlier -- so that migrations can create a new one from scratch.

O instantâneo do modelo de dadosThe data model snapshot

As migrações criam um instantâneo do esquema de banco de dados atual em Migrations/SchoolContextModelSnapshot.cs.Migrations creates a snapshot of the current database schema in Migrations/SchoolContextModelSnapshot.cs. Quando você adiciona uma migração, o EF determina o que foi alterado, comparando o modelo de dados com o arquivo de instantâneo.When you add a migration, EF determines what changed by comparing the data model to the snapshot file.

Ao excluir uma migração, use o comando dotnet ef migrations remove.When deleting a migration, use the dotnet ef migrations remove command. dotnet ef migrations remove exclui a migração e garante que o instantâneo seja redefinido corretamente.dotnet ef migrations remove deletes the migration and ensures the snapshot is correctly reset.

Confira Migrações do EF Core em ambientes de equipe para obter mais informações de como o arquivo de instantâneo é usado.See EF Core Migrations in Team Environments for more information about how the snapshot file is used.

Aplicar a migração ao banco de dadosApply the migration to the database

Na janela Comando, insira o comando a seguir para criar o banco de dados e tabelas nele.In the command window, enter the following command to create the database and tables in it.

dotnet ef database update

A saída do comando é semelhante ao comando migrations add, exceto que os logs para os comandos SQL que configuram o banco de dados são exibidos.The output from the command is similar to the migrations add command, except that you see logs for the SQL commands that set up the database. A maioria dos logs é omitida na seguinte saída de exemplo.Most of the logs are omitted in the following sample output. Se você preferir não ver esse nível de detalhe em mensagens de log, altere o nível de log no arquivo appsettings.Development.json.If you prefer not to see this level of detail in log messages, you can change the log level in the appsettings.Development.json file. Para obter mais informações, consulte Registro em log no ASP.NET Core.For more information, see Registro em log no ASP.NET Core.

info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
      User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
      Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider 'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[200101]
      Executed DbCommand (467ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
      CREATE DATABASE [ContosoUniversity2];
info: Microsoft.EntityFrameworkCore.Database.Command[200101]
      Executed DbCommand (20ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      CREATE TABLE [__EFMigrationsHistory] (
          [MigrationId] nvarchar(150) NOT NULL,
          [ProductVersion] nvarchar(32) NOT NULL,
          CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
      );

<logs omitted for brevity>

info: Microsoft.EntityFrameworkCore.Database.Command[200101]
      Executed DbCommand (3ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
      VALUES (N'20170816151242_InitialCreate', N'2.0.0-rtm-26452');
Done.

Use o Pesquisador de Objetos do SQL Server para inspecionar o banco de dados como você fez no primeiro tutorial.Use SQL Server Object Explorer to inspect the database as you did in the first tutorial. Você observará a adição de uma tabela __EFMigrationsHistory que controla quais migrações foram aplicadas ao banco de dados.You'll notice the addition of an __EFMigrationsHistory table that keeps track of which migrations have been applied to the database. Exiba os dados dessa tabela e você verá uma linha para a primeira migração.View the data in that table and you'll see one row for the first migration. (O último log no exemplo de saída da CLI anterior mostra a instrução INSERT que cria essa linha.)(The last log in the preceding CLI output example shows the INSERT statement that creates this row.)

Execute o aplicativo para verificar se tudo ainda funciona como antes.Run the application to verify that everything still works the same as before.

Página Índice de Alunos

CLI (interface de linha de comando) vs. PMC (Console do Gerenciador de Pacotes)Command-line interface (CLI) vs. Package Manager Console (PMC)

As ferramentas do EF para gerenciamento de migrações estão disponíveis por meio dos comandos da CLI do .NET Core ou de cmdlets do PowerShell na janela PMC (Console do Gerenciador de Pacotes) do Visual Studio.The EF tooling for managing migrations is available from .NET Core CLI commands or from PowerShell cmdlets in the Visual Studio Package Manager Console (PMC) window. Este tutorial mostra como usar a CLI, mas você poderá usar o PMC se preferir.This tutorial shows how to use the CLI, but you can use the PMC if you prefer.

Os comandos do EF para os comandos do PMC estão no pacote Microsoft.EntityFrameworkCore.Tools.The EF commands for the PMC commands are in the Microsoft.EntityFrameworkCore.Tools package. Esse pacote está incluído no metapacote Microsoft.AspNetCore.App, portanto você não precisa adicionar uma referência de pacote se o aplicativo tem uma referência de pacote ao Microsoft.AspNetCore.App.This package is included in the Microsoft.AspNetCore.App metapackage, so you don't need to add a package reference if your app has a package reference for Microsoft.AspNetCore.App.

Importante: esse não é o mesmo pacote que é instalado para a CLI com a edição do arquivo .csproj.Important: This isn't the same package as the one you install for the CLI by editing the .csproj file. O nome deste termina com Tools, ao contrário do nome do pacote da CLI que termina com Tools.DotNet.The name of this one ends in Tools, unlike the CLI package name which ends in Tools.DotNet.

Para obter mais informações sobre os comandos da CLI, consulte CLI do .NET Core.For more information about the CLI commands, see .NET Core CLI.

Para obter mais informações sobre os comandos do PMC, consulte Console do Gerenciador de Pacotes (Visual Studio).For more information about the PMC commands, see Package Manager Console (Visual Studio).

ResumoSummary

Neste tutorial, você viu como criar e aplicar sua primeira migração.In this tutorial, you've seen how to create and apply your first migration. No próximo tutorial, você começará examinando tópicos mais avançados com a expansão do modelo de dados.In the next tutorial, you'll begin looking at more advanced topics by expanding the data model. Ao longo do processo, você criará e aplicará migrações adicionais.Along the way you'll create and apply additional migrations.