ASP.NET Core 1.x’ten 2.0’a geçiş

Makale
11/30/2023

Bu makalede, mevcut bir ASP.NET Core 1.x projesini ASP.NET Core 2.0'a güncelleştirme işleminde size yol gösterilmektedir. Uygulamanızı ASP.NET Core 2.0'a geçirmek, birçok yeni özellik ve performans geliştirmelerinden yararlanmanızı sağlar.

Mevcut ASP.NET Core 1.x uygulamaları, sürüme özgü proje şablonlarını temel alır. ASP.NET Core çerçevesi geliştikçe, proje şablonları ve bunların içinde yer alan başlangıç kodu da gelişir. ASP.NET Core çerçevesini güncelleştirmeye ek olarak uygulamanızın kodunu da güncelleştirmeniz gerekir.

Ön koşullar

Bkz. ASP.NET Core kullanmaya başlama.

Hedef Çerçeve Bilinen Adını (TFM) Güncelleştirme

.NET Core'un hedeflenmesi gereken projeler ,NET Core 2.0'dan büyük veya buna eşit bir sürümün TFM’sini kullanmalıdır. .csproj dosyasındaki <TargetFramework> düğümünü arayın ve iç metnini netcoreapp2.0 ile değiştirin:

<TargetFramework>netcoreapp2.0</TargetFramework>

.NET Framework'ü hedefleyen projeler, .NET Framework 4.6.1'e eşit veya daha büyük bir sürümün TFM'sini kullanmalıdır. .csproj dosyasındaki <TargetFramework> düğümünü arayın ve iç metnini net461 ile değiştirin:

<TargetFramework>net461</TargetFramework>

Dekont

.NET Core 2.0, .NET Core 1.x'ten çok daha büyük bir yüzey alanı sunar. .NET Framework'ü yalnızca .NET Core 1.x'teki eksik API'ler nedeniyle hedefliyorsanız, .NET Core 2.0'ı hedeflemek büyük olasılıkla işe yarayacaktır.

Proje dosyası <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion> içeriyorsa bu GitHub sorununa bakın.

içinde .NET Core SDK sürümünü güncelleştirme global.json

Çözümünüz belirli bir .NET Core SDK sürümünü hedeflemek için bir global.json dosya kullanıyorsa, özelliğini makinenizde yüklü olan 2.0 sürümünü kullanacak şekilde güncelleştirin version :

{
  "sdk": {
    "version": "2.0.0"
  }
}

Paket başvurularını güncelleştirme

Bir 1.x projesindeki .csproj dosyası, proje tarafından kullanılan her NuGet paketini listeler.

.NET Core 2.0'ı hedefleyen bir ASP.NET Core 2.0 projesinde, .csproj dosyasındaki tek bir meta paket başvurusu paket koleksiyonunun yerini alır:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

ASP.NET Core 2.0 ve Entity Framework Core 2.0'ın tüm özellikleri meta pakete dahildir.

.NET Framework hedefleyen ASP.NET Core 2.0 projeleri ayrı olarak NuGet paketlerine başvurmaya devam etmelidir. Her <PackageReference /> düğümün Version özniteliğini 2.0.0 olarak güncelleştirin.

Örneğin, .NET Framework hedefleyen tipik bir ASP.NET Core 2.0 projesinde kullanılan <PackageReference /> düğümlerin listesi aşağıda verilmiştir:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

Microsoft.Extensions.CommandLineUtils paketi kullanım dışı bırakıldı. Hala kullanılabilir ancak desteklenmiyor.

.NET Core CLI araçlarını güncelleştirme

.csproj dosyasında, her <DotNetCliToolReference /> düğümün Version özniteliğini 2.0.0 olarak güncelleştirin.

Örneğin, .NET Core 2.0’ı hedefleyen tipik bir ASP.NET Core 2.0 projesinde kullanılan CLI araçlarının listesi aşağıda verilmiştir:

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

Paket Hedef Geri Dönüş özelliğini yeniden adlandırma

1.x projesinin .csproj dosyası bir PackageTargetFallback düğümü ve değişken kullanır:

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

Hem düğümü hem de değişkeni AssetTargetFallback olarak yeniden adlandırın:

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Program.cs dosyasında Main yöntemini güncelleştirme

1.x projelerinde Program.cs öğesinin Main yöntemi şöyle görünüyordu:

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

2.0 projelerinde Program.cs öğesinin Main yöntemi basitleştirilmiştir:

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

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

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

Bu yeni 2.0 modelinin benimsenmesi şiddetle tavsiye edilir ve Entity Framework (EF) Çekirdek Geçişleri gibi ürün özelliklerinin çalışması için gereklidir. Örneğin, Paket Yöneticisi Konsolu penceresinden Update-Database veya komut satırından (ASP.NET Core 2.0'a dönüştürülen projelerde) dotnet ef database update çalıştırıldığında aşağıdaki hata oluşur:

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Yapılandırma sağlayıcıları ekleme

1.x projelerinde, bir uygulamaya yapılandırma sağlayıcıları ekleme Startup oluşturucusu aracılığıyla gerçekleştirilir. ConfigurationBuilder örneği oluşturma, ilgili sağlayıcıları yükleme (ortam değişkenleri, uygulama ayarları vb.) ve öğesinin bir IConfigurationRoot üyesini başlatma adımlarını içerir.

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

Önceki örnek, Configuration üyesini appsettings.json öğesinden yapılandırma ayarlarıyla ve IHostingEnvironment.EnvironmentName özelliğiyle eşleşen herhangi bir appsettings.{Environment}.json dosyasıyla yükler. Bu dosyaların konumu Startup.cs ile aynı yoldadır.

2.0 projelerinde, 1.x projelerine özgü ortak yapılandırma kodu arka planda çalışır. Örneğin, ortam değişkenleri ve uygulama ayarları başlangıçta yüklenir. Eşdeğer Startup.cs kodu, eklenen örnekle IConfiguration başlatmaya küçültülür:

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

WebHostBuilder.CreateDefaultBuilder tarafından eklenen varsayılan sağlayıcıları kaldırmak için, ConfigureAppConfiguration içindeki IConfigurationBuilder.Sources özelliğinde Clear yöntemini çağırın. Sağlayıcıları geri eklemek için Program.cs içindeki ConfigureAppConfiguration yöntemini kullanabilirler:

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

Önceki kod parçacığında CreateDefaultBuilder yöntemi tarafından kullanılan yapılandırma burada görülebilir.

Daha fazla bilgi için, bkz. ASP.NET Core’da yapılandırma analizi.

Veritabanı başlatma kodunu taşıma

1.x kullanan EF Core 1.x projelerinde, aşağıdaki gibi dotnet ef migrations add bir komut yapar:

Bir Startup örneği oluşturur
Bağımlılık ekleme ile tüm hizmetleri kaydetmek için ConfigureServices yöntemini çağırır (DbContext türleri dahil)
Gerekli görevlerini gerçekleştirir

2.0 kullanan EF Core 2.0 projelerinde, Program.BuildWebHost uygulama hizmetlerini almak için çağrılır. 1.x'in aksine, bu, Startup.Configure çağırmanın ek yan etkisine sahiptir. 1.x uygulamanız Configure yönteminde veritabanı başlatma kodunu çağırırsa beklenmeyen sorunlar oluşabilir. Örneğin, veritabanı henüz yoksa, geçiş kodu Migrations komutu yürütmeden EF Core önce çalışır. Bu sorun, veritabanı henüz mevcut değilse dotnet ef migrations list komutunun başarısız olmasına neden olur.

Startup.cs öğesinin Configure yönteminde aşağıdaki 1.x tohum başlatma kodunu göz önünde bulundurun:

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

2.0 projelerinde SeedData.Initialize çağrısını Program.cs öğesinin Main yöntemine taşıyın:

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

2.0 itibarıyla web konağını derleme ve yapılandırma dışında, BuildWebHost içinde herhangi bir işlem yapmak kötü bir uygulamadır. Uygulamayı çalıştırmakla ilgili her şey BuildWebHost öğesinin dışında ele alınmalıdır - tipik olarak Program.cs öğesinin Main yönteminde.

Razor görünümü derleme ayarını gözden geçirme

Daha hızlı uygulama başlatma süresi ve daha küçük yayımlanmış paketler sizin için son derece önemlidir. Bu nedenle, Razor görünüm derlemesi, ASP.NET Core 2.0'da varsayılan olarak etkindir.

MvcRazorCompileOnPublish özelliğinin true olarak ayarlanması artık gerekli değildir. Görünüm derlemesini devre dışı bırakmadığınız sürece özelliği .csproj dosyasından kaldırılabilir.

.NET Framework'ü hedeflerken, yine de .csproj dosyanızda Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet paketine açıkça başvurmanız gerekir:

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

Application Insights "light-up" özelliklerine güvenme

Uygulama performansı izlemesinin zahmetsiz kurulumu önemlidir. Artık Visual Studio 2017 araçlarında bulunan yeni Application Insights "light-up" özelliklerine güvenebilirsiniz.

Visual Studio 2017'de oluşturulan ASP.NET Core 1.1 projeleri varsayılan olarak Application Insights'a eklenmiştir. Application Insights SDK'sını doğrudan, Program.cs ve Startup.cs dışında kullanmıyorsanız şu adımları izleyin:

.NET Core'u hedefliyorsanız, .csproj dosyasından aşağıdaki <PackageReference /> düğümü kaldırın:
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

.NET Core'u hedefliyorsanız UseApplicationInsights uzantı yöntemi çağırmayı Program.cs adresinden kaldırın:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

_Layout.cshtml uygulamasından Application Insights istemci tarafı API çağrısını kaldırın. Aşağıdaki iki kod satırından oluşur:
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Application Insights SDK'sını doğrudan kullanıyorsanız, kullanmaya devam edin. 2.0 meta paketi, Application Insights'ın en son sürümünü içerdiğinden, eski bir sürüme başvuruyorsanız paket eski sürüme düşürme hatası görüntülenir.

Kimlik doğrulaması/Identity geliştirmelerini benimseme

ASP.NET Core 2.0, yeni bir kimlik doğrulaması modeline ve ASP.NET Core Identity için bir dizi önemli değişikliğe sahiptir. Projenizi Bireysel Kullanıcı Hesapları etkinken oluşturduysanız veya el ile kimlik doğrulaması veya Identity eklediyseniz, bkz.Kimlik Doğrulamayı ve Identity öğesini ASP.NET Core 2.0'a Taşıma.

Ek kaynaklar

ASP.NET Core 2.0'da Önemli Değişiklikler

ASP.NET Core 1.x’ten 2.0’a geçiş

Ön koşullar

Hedef Çerçeve Bilinen Adını (TFM) Güncelleştirme

içinde .NET Core SDK sürümünü güncelleştirme global.json

Paket başvurularını güncelleştirme

.NET Core CLI araçlarını güncelleştirme

Paket Hedef Geri Dönüş özelliğini yeniden adlandırma

Program.cs dosyasında Main yöntemini güncelleştirme

Yapılandırma sağlayıcıları ekleme

Veritabanı başlatma kodunu taşıma

Razor görünümü derleme ayarını gözden geçirme

Application Insights "light-up" özelliklerine güvenme

Kimlik doğrulaması/Identity geliştirmelerini benimseme

Ek kaynaklar

Geri Bildirim

Ek kaynaklar