Atualizando aplicativos de versões anteriores ao EF Core 2.0Upgrading applications from previous versions to EF Core 2.0

Procedimentos comuns a todos os aplicativosProcedures Common to All Applications

Atualizando um aplicativo existente para EF Core 2.0 pode exigir:Updating an existing application to EF Core 2.0 may require:

  1. Atualização da plataforma do .NET de destino do aplicativo para um que suporte o .NET 2.0 padrão.Upgrading the target .NET platform of the application to one that supports .NET Standard 2.0. Consulte plataformas com suporte para obter mais detalhes.See Supported Platforms for more details.

  2. Identifica um provedor para o banco de dados de destino que é compatível com o EF Core 2.0.Identify a provider for the target database which is compatible with EF Core 2.0. Consulte EF Core 2.0 requer um provedor de banco de 2.0 dados abaixo.See EF Core 2.0 requires a 2.0 database provider below.

  3. Atualizar todos os pacotes de EF Core (tempo de execução e ferramentas) 2.0.Upgrading all the EF Core packages (runtime and tooling) to 2.0. Consulte instalando EF Core para obter mais detalhes.Refer to Installing EF Core for more details.

  4. Faça as alterações necessárias de código para compensar alterações significativas.Make any necessary code changes to compensate for breaking changes. Consulte o alterações significativas seção abaixo para obter mais detalhes.See the Breaking Changes section below for more details.

Aplicativos do ASP.NET CoreASP.NET Core applications

  1. Consulte em particular a novo padrão para inicializar o provedor de serviços do aplicativo descrito abaixo.See in particular the new pattern for initializing the application's service provider described below.

Dica

A adoção desse novo padrão quando atualizar aplicativos 2.0 é altamente recomendado e é necessário para recursos de produto como Entity Framework Core migrações para trabalhar.The adoption of this new pattern when updating applications to 2.0 is highly recommended and is required in order for product features like Entity Framework Core Migrations to work. A outra alternativa comum é implementar IDesignTimeDbContextFactory<TContext >.The other common alternative is to implement IDesignTimeDbContextFactory<TContext>.

  1. Aplicativos voltados para o ASP.NET 2.0 de núcleo podem usar o EF Core 2.0 sem dependências adicionais além de provedores de banco de dados de terceiros.Applications targeting ASP.NET Core 2.0 can use EF Core 2.0 without additional dependencies besides third party database providers. No entanto, aplicativos destinados a versões anteriores do ASP.NET Core precisam atualizar para o ASP.NET 2.0 de núcleo para usar o EF Core 2.0.However, applications targeting previous versions of ASP.NET Core need to upgrade to ASP.NET Core 2.0 in order to use EF Core 2.0. Para obter mais detalhes sobre como atualizar aplicativos ASP.NET Core 2.0, consulte a documentação do ASP.NET Core no assunto.For more details on upgrading ASP.NET Core applications to 2.0 see the ASP.NET Core documentation on the subject.

Alterações significativasBreaking Changes

Levamos a oportunidade de refinar significativamente os comportamentos no 2.0 e APIs existentes.We have taken the opportunity to significantly refine our existing APIs and behaviors in 2.0. Existem alguns aprimoramentos que podem exigir a modificação do código de aplicativo existente, embora acreditamos que para a maioria dos aplicativos o impacto será baixo, na maioria dos casos que exigem apenas recompilação e alterações mínimas de interativa para substituir as APIs obsoletas.There are a few improvements that can require modifying existing application code, although we believe that for the majority of applications the impact will be low, in most cases requiring just recompilation and minimal guided changes to replace obsolete APIs.

Nova maneira de obter serviços de aplicativoNew way of getting application services

O padrão recomendado para aplicativos da web de ASP.NET Core foi atualizado para 2.0 de forma que interrompeu a lógica de tempo de design que EF principal usada em 1. x.The recommended pattern for ASP.NET Core web applications has been updated for 2.0 in a way that broke the design-time logic EF Core used in 1.x. Anteriormente em tempo de design, Core EF tentar invocar Startup.ConfigureServices diretamente para acessar o provedor de serviços do aplicativo.Previously at design-time, EF Core would try to invoke Startup.ConfigureServices directly in order to access the application's service provider. No ASP.NET 2.0 de núcleo, a configuração é inicializada fora do Startup classe.In ASP.NET Core 2.0, Configuration is initialized outside of the Startup class. Aplicativos que utilizam o EF Core geralmente acessam sua cadeia de caracteres de conexão de configuração, portanto Startup por si só não é suficiente.Applications using EF Core typically access their connection string from Configuration, so Startup by itself is no longer sufficient. Se você atualizar um aplicativo do ASP.NET Core 1. x, você receberá o seguinte erro ao usar as ferramentas de EF Core.If you upgrade an ASP.NET Core 1.x application, you may receive the following error when using the EF Core tools.

Nenhum construtor sem parâmetros foi encontrado em 'ApplicationContext'.No parameterless constructor was found on 'ApplicationContext'. Adicione um construtor sem parâmetros para 'ApplicationContext' ou adicione uma implementação de ' IDesignTimeDbContextFactory<ApplicationContext>' no mesmo assembly como 'ApplicationContext'Either add a parameterless constructor to 'ApplicationContext' or add an implementation of 'IDesignTimeDbContextFactory<ApplicationContext>' in the same assembly as 'ApplicationContext'

Foi adicionado um novo gancho de tempo de design no modelo de padrão do ASP.NET Core 2.0.A new design-time hook has been added in ASP.NET Core 2.0's default template. Estático Program.BuildWebHost método permite que o EF principal acessar o provedor de serviços do aplicativo em tempo de design.The static Program.BuildWebHost method enables EF Core to access the application's service provider at design time. Se você estiver atualizando um aplicativo do ASP.NET Core 1. x, você precisará atualizar Program classe para ser semelhante à seguinte.If you are upgrading an ASP.NET Core 1.x application, you will need to update you Program class to resemble the following.

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2._0App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

IDbContextFactory renomeadoIDbContextFactory renamed

Para dar suporte a padrões de diversos aplicativos e fornecer aos usuários mais controle sobre como suas DbContext é usada em tempo de design, nós fornecemos, no passado, o IDbContextFactory<TContext> interface.In order to support diverse application patterns and give users more control over how their DbContext is used at design time, we have, in the past, provided the IDbContextFactory<TContext> interface. Em tempo de design, as ferramentas principais EF descobrirá implementações dessa interface em seu projeto e usá-lo para criar DbContext objetos.At design-time, the EF Core tools will discover implementations of this interface in your project and use it to create DbContext objects.

Essa interface tiver um nome muito geral que alguns usuários para tentar novamente usando-o para outro de enganar DbContext-criação de cenários.This interface had a very general name which mislead some users to try re-using it for other DbContext-creating scenarios. Foram pega de surpresa quando as ferramentas de EF, em seguida, tentou usar sua implementação em tempo de design e causados comandos como Update-Database ou dotnet ef database update falha.They were caught off guard when the EF Tools then tried to use their implementation at design-time and caused commands like Update-Database or dotnet ef database update to fail.

Para comunicar-se a semântica de tempo de design forte desta interface, podemos ter renomeado para IDesignTimeDbContextFactory<TContext>.In order to communicate the strong design-time semantics of this interface, we have renamed it to IDesignTimeDbContextFactory<TContext>.

Para obter o 2.0 versão o IDbContextFactory<TContext> ainda existe, mas está marcado como obsoleto.For the 2.0 release the IDbContextFactory<TContext> still exists but is marked as obsolete.

DbContextFactoryOptions removidoDbContextFactoryOptions removed

Devido às alterações de ASP.NET Core 2.0 descritas acima, descobrimos que DbContextFactoryOptions não era mais necessário no novo IDesignTimeDbContextFactory<TContext> interface.Because of the ASP.NET Core 2.0 changes described above, we found that DbContextFactoryOptions was no longer needed on the new IDesignTimeDbContextFactory<TContext> interface. Aqui estão as alternativas, que você deve usar em vez disso.Here are the alternatives you should be using instead.

DbContextFactoryOptionsDbContextFactoryOptions AlternativaAlternative
ApplicationBasePathApplicationBasePath AppContext.BaseDirectoryAppContext.BaseDirectory
ContentRootPathContentRootPath Directory.GetCurrentDirectory()Directory.GetCurrentDirectory()
EnvironmentNameEnvironmentName Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")

Diretório de trabalho de tempo de design alteradoDesign-time working directory changed

As alterações do ASP.NET Core 2.0 também necessário o diretório de trabalho usado por dotnet ef para se alinhar com o diretório de trabalho usado pelo Visual Studio ao executar seu aplicativo.The ASP.NET Core 2.0 changes also required the working directory used by dotnet ef to align with the working directory used by Visual Studio when running your application. Um efeito colateral observável disso é que SQLite nomes de arquivos agora estão em relação ao diretório do projeto e não no diretório de saída que costumavam ser.One observable side effect of this is that SQLite filenames are now relative to the project directory and not the output directory like they used to be.

EF Core 2.0 requer um provedor de banco de 2.0 dadosEF Core 2.0 requires a 2.0 database provider

Para o EF Core 2.0 fizemos muitas simplificações e aprimoramentos nos provedores de banco de dados de maneira de trabalho.For EF Core 2.0 we have made many simplifications and improvements in the way database providers work. Isso significa que provedores 1.0. x e 1.1 não funcionarão com o EF Core 2.0.This means that 1.0.x and 1.1.x providers will not work with EF Core 2.0.

Os provedores SQL Server e SQLite são fornecidos pela equipe do EF e 2.0 versões estarão disponíveis como parte do 2.0 de versão.The SQL Server and SQLite providers are shipped by the EF team and 2.0 versions will be available as part of the 2.0 release. Os provedores de terceiros do código-fonte aberto para SQL Compact, PostgreSQL, e MySQL estão sendo atualizadas para 2.0.The open-source third party providers for SQL Compact, PostgreSQL, and MySQL are being updated for 2.0. Para todos os outros provedores, entre em contato com o gravador de provedor.For all other providers, please contact the provider writer.

Eventos de log e diagnóstico foram alteradosLogging and Diagnostics events have changed

Observação: essas alterações não devem afetar a maioria dos códigos de aplicativo.Note: these changes should not impact most application code.

As identificações de evento das mensagens enviadas para um ILogger foram alterados no 2.0.The event IDs for messages sent to an ILogger have changed in 2.0. As identificações de evento são exclusivas em código EF principal.The event IDs are now unique across EF Core code. Essas mensagens agora também pode seguir o padrão para o log estruturado usado por, por exemplo, o MVC.These messages now also follow the standard pattern for structured logging used by, for example, MVC.

Categorias de agente de log também foram alterados.Logger categories have also changed. Há agora um conjunto conhecido de categorias acessados por meio de DbLoggerCategory.There is now a well-known set of categories accessed through DbLoggerCategory.

DiagnosticSource eventos agora usam os mesmos nomes de ID de evento como correspondente ILogger mensagens.DiagnosticSource events now use the same event ID names as the corresponding ILogger messages. As cargas do evento são todos os tipos nominais derivados de EventData.The event payloads are all nominal types derived from EventData.

Categorias, tipos de carga e IDs de eventos estão documentadas no CoreEventId e RelationalEventId classes.Event IDs, payload types, and categories are documented in the CoreEventId and the RelationalEventId classes.

IDs também foram movidos de Microsoft.EntityFrameworkCore.Infraestructure para o novo namespace Microsoft.EntityFrameworkCore.Diagnostics.IDs have also moved from Microsoft.EntityFrameworkCore.Infraestructure to the new Microsoft.EntityFrameworkCore.Diagnostics namespace.

Alterações de metadados relacionais API Core EFEF Core relational metadata API changes

EF Core 2.0 agora criará outro IModel para cada provedor diferente que está sendo usado.EF Core 2.0 will now build a different IModel for each different provider being used. Isso normalmente é transparente para o aplicativo.This is usually transparent to the application. Isso facilitou uma simplificação de APIs de metadados de nível inferior, de modo que qualquer acesso ao comuns conceitos de metadados relacionais sempre é feita por meio de uma chamada para .Relational em vez de .SqlServer, .Sqlite, etc. Por exemplo, 1.1 código como este:This has facilitated a simplification of lower-level metadata APIs such that any access to common relational metadata concepts is always made through a call to .Relational instead of .SqlServer, .Sqlite, etc. For example, 1.1.x code like this:

var tableName = context.Model.FindEntityType(typeof(User)).SqlServer().TableName;

Agora deve ser escrito como este:Should now be written like this:

var tableName = context.Model.FindEntityType(typeof(User)).Relational().TableName;

Em vez de usar os métodos, como ForSqlServerToTable, métodos de extensão estão agora disponíveis para escrever código condicional com base no provedor atual em uso.Instead of using methods like ForSqlServerToTable, extension methods are now available to write conditional code based on the current provider in use. Por exemplo:For example:

modelBuilder.Entity<User>().ToTable(
    Database.IsSqlServer() ? "SqlServerName" : "OtherName");

Observe que essa alteração se aplica apenas a APIs/metadados que está definido para todos os provedores relacionais.Note that this change only applies to APIs/metadata that is defined for all relational providers. A API e metadados permanece o mesmo quando ele é específico para apenas um único provedor.The API and metadata remains the same when it is specific to only a single provider. Por exemplo, os índices clusterizados são específicos para SQL Server, portanto ForSqlServerIsClustered e .SqlServer().IsClustered() deve ser usado.For example, clustered indexes are specific to SQL Sever, so ForSqlServerIsClustered and .SqlServer().IsClustered() must still be used.

Não assumir o controle do provedor de serviços EFDon’t take control of the EF service provider

Núcleo EF usa interno IServiceProvider (ou seja, um contêiner de injeção de dependência) para sua implementação interna.EF Core uses an internal IServiceProvider (i.e. a dependency injection container) for its internal implementation. Aplicativos devem permitir que o EF principal criar e gerenciar esse provedor, exceto em casos especiais.Applications should allow EF Core to create and manage this provider except in special cases. Altamente Considere remover todas as chamadas para UseInternalServiceProvider.Strongly consider removing any calls to UseInternalServiceProvider. Se um aplicativo precisa chamar UseInternalServiceProvider, em seguida, considere um problema de arquivamento para investigamos outras maneiras de tratar o cenário.If an application does need to call UseInternalServiceProvider, then please consider filing an issue so we can investigate other ways to handle your scenario.

Chamando AddEntityFramework, AddEntityFrameworkSqlServer, etc. não é necessário pelo código do aplicativo, a menos que UseInternalServiceProvider também é chamado.Calling AddEntityFramework, AddEntityFrameworkSqlServer, etc. is not required by application code unless UseInternalServiceProvider is also called. Remova as chamadas existentes para AddEntityFramework ou AddEntityFrameworkSqlServer, etc. AddDbContext ainda deve ser usada da mesma forma como antes.Remove any existing calls to AddEntityFramework or AddEntityFrameworkSqlServer, etc. AddDbContext should still be used in the same way as before.

Bancos de dados na memória devem ser nomeados.In-memory databases must be named

O banco de dados sem nome por na memória global foi removido e, em vez disso, todos os bancos de dados na memória devem ser nomeados.The global unnamed in-memory database has been removed and instead all in-memory databases must be named. Por exemplo:For example:

optionsBuilder.UseInMemoryDatabase("MyDatabase");

Isso cria/usa um banco de dados com o nome "MyDatabase".This creates/uses a database with the name “MyDatabase”. Se UseInMemoryDatabase é chamado novamente com o mesmo nome, o mesmo banco de dados na memória será usado, permitindo que ele seja compartilhado por várias instâncias de contexto.If UseInMemoryDatabase is called again with the same name, then the same in-memory database will be used, allowing it to be shared by multiple context instances.

Alterações de API de somente leituraRead-only API changes

IsReadOnlyBeforeSave, IsReadOnlyAferSave, e IsStoreGeneratedAlways obsoletos e substituídos por BeforeSaveBehavior e AfterSaveBehavior.IsReadOnlyBeforeSave, IsReadOnlyAferSave, and IsStoreGeneratedAlways have been obsoleted and replaced with BeforeSaveBehavior and AfterSaveBehavior. Esses comportamentos se aplicam a qualquer propriedade (não apenas propriedades geradas pelo repositório) e determinar como o valor da propriedade deve ser usado ao inserir em uma linha de banco de dados (BeforeSaveBehavior) ou quando uma existente de atualização de banco de dados linha (AfterSaveBehavior).These behaviors apply to any property (not only store-generated properties) and determine how the value of the property should be used when inserting into a database row (BeforeSaveBehavior) or when updating an existing database row (AfterSaveBehavior).

Propriedades marcadas como ValueGenerated.OnAddOrUpdate (por exemplo, para colunas computadas) por padrão ignorará qualquer valor atualmente definido na propriedade.Properties marked as ValueGenerated.OnAddOrUpdate (e.g. for computed columns) will by default ignore any value currently set on the property. Isso significa que um valor gerado pelo repositório sempre será obtido independentemente se nenhum valor foi definido ou modificado na entidade controlada.This means that a store-generated value will always be obtained regardless of whether any value has been set or modified on the tracked entity. Isso pode ser alterado definindo outro Before\AfterSaveBehavior.This can be changed by setting a different Before\AfterSaveBehavior.

Novo comportamento de exclusão ClientSetNullNew ClientSetNull delete behavior

Em versões anteriores, DeleteBehavior.Restrict teve um comportamento para entidades controladas pelo contexto que mais fechado correspondentes SetNull semântica.In previous releases, DeleteBehavior.Restrict had a behavior for entities tracked by the context that more closed matched SetNull semantics. No EF Core 2.0, um novo ClientSetNull comportamento foi introduzido como padrão para relações opcionais.In EF Core 2.0, a new ClientSetNull behavior has been introduced as the default for optional relationships. Esse comportamento tem SetNull semântica para entidades controladas e Restrict comportamento para bancos de dados criados usando EF Core.This behavior has SetNull semantics for tracked entities and Restrict behavior for databases created using EF Core. Em nossa experiência, esses são os comportamentos mais esperado/úteis para entidades controladas e o banco de dados.In our experience, these are the most expected/useful behaviors for tracked entities and the database. DeleteBehavior.RestrictAgora é cumprido para entidades controladas quando definidas para relações opcionais.DeleteBehavior.Restrict is now honored for tracked entities when set for optional relationships.

Pacotes de tempo de design de provedor removidosProvider design-time packages removed

O Microsoft.EntityFrameworkCore.Relational.Design pacote tiver sido removido.The Microsoft.EntityFrameworkCore.Relational.Design package has been removed. Conteúdo do arquivo foram consolidado em Microsoft.EntityFrameworkCore.Relational e Microsoft.EntityFrameworkCore.Design.It's contents were consolidated into Microsoft.EntityFrameworkCore.Relational and Microsoft.EntityFrameworkCore.Design.

Isso é propagada para os pacotes de tempo de design do provedor.This propagates into the provider design-time packages. Esses pacotes (Microsoft.EntityFrameworkCore.Sqlite.Design, Microsoft.EntityFrameworkCore.SqlServer.Design, etc.) foram removidas e seus conteúdos são consolidados em pacotes do provedor principal.Those packages (Microsoft.EntityFrameworkCore.Sqlite.Design, Microsoft.EntityFrameworkCore.SqlServer.Design, etc.) were removed and their contents consolidated into the main provider packages.

Para habilitar Scaffold-DbContext ou dotnet ef dbcontext scaffold no EF Core 2.0, você só precisa referenciar o pacote único provedor:To enable Scaffold-DbContext or dotnet ef dbcontext scaffold in EF Core 2.0, you only need to reference the single provider package:

<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer"
    Version="2.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools"
    Version="2.0.0"
    PrivateAssets="All" />
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
    Version="2.0.0" />