ASP.NET Core 2.1.0-preview1 now available

Today we’re very happy to announce that the first preview of the next minor release of ASP.NET Core and .NET Core is now available for you to try out. We’ve been working hard on this release over the past months, along with many folks from the community, and it’s now ready for a wider audience to try it out and provide the feedback that will continue to shape the release.

You can read about .NET Core 2.1.0-preview1 over on their blog.

You can also read about Entity Framework Core 2.1.0-preview1 on their blog.

How do I get it?

You can download the new .NET Core SDK for 2.1.0-preview1 (which includes ASP.NET Core 2.1.0-preview1) from https://www.microsoft.com/net/download/dotnet-core/sdk-2.1.300-preview1

Visual Studio 2017 version requirements

Customers using Visual Studio 2017 should also install (in addition to the SDK above) and use the Preview channel (15.6 Preview 6 at the time of writing) when working with .NET Core and ASP.NET Core 2.1 projects. .NET Core 2.1 projects require Visual Studio 2017 15.6 or greater.

Impact to machines

Please note that given this is a preview release there are likely to be known issues and as-yet-to-be-discovered bugs. While .NET Core SDK and runtime installs are side-by-side on your machine, your default SDK will become the latest version, which in this case will be the preview. If you run into issues working on existing projects using earlier versions of .NET Core after installing the preview SDK, you can force specific projects to use an earlier installed version of the SDK using a global.json file as documented here. Please log an issue if you run into such cases as SDK releases are intended to be backwards compatible.

Already published applications running on earlier versions of .NET Core and ASP.NET Core shouldn’t be impacted by installing the preview. That said, we don’t recommend installing previews on machines running critical workloads.

New features

You can see a summary of the new features in 2.1 in the roadmap post we published previously.

Furthermore, we’re publishing a series of posts here that go over the new feature areas in detail. We’ll update this post with links to these posts as they go live over the coming days:

Using ASP.NET Core previews in Azure App Service
Introducing HttpClientFactory
Improvements for using HTTPS
Improvements for building Web APIs
Introducing compatibility version in MVC
Getting started with SignalR
Introducing global tools
Using Razor UI in class libraries
Improvements for GDPR
Improvements to the Kestrel HTTP server
Improvements to IIS hosting
Functional testing of MVC applications
Introducing Identity UI as a library
Hosting non-server apps with GenericHostBuilder

Announcements and release notes

You can see all the announcements published pertaining to this release at https://github.com/aspnet/Announcements/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.1.0

Release notes will be available shortly at https://github.com/aspnet/Home/releases/tag/2.1.0-preview1

Giving feedback

The main purpose of providing previews like this is to solicit feedback from customers such that we can refine and improve the changes in time for the final release. We intend to release a second preview within the next couple of months, followed by a single RC release (with “go-live” license and support) before the final RTW release.

Please provide feedback by logging issues in the appropriate repository at https://github.com/aspnet or https://github.com/dotnet. The posts on specific topics above will provide direct links to the most appropriate place to log issues for the features detailed.

Migrating an ASP.NET Core 2.0.x project to 2.1.0-preview1

Follow these steps to migrate an existing ASP.NET Core 2.0.x project to 2.1.0-preview1:

Open the project’s CSPROJ file and change the value of the <TargetFramework> element to netcoreapp2.1
- Projects targeting .NET Framework rather than .NET Core, e.g. net471, don’t need to do this
In the same file, update the versions of the various <PackageReference> elements for any Microsoft.AspNetCore, Microsoft.Extensions, and Microsoft.EntityFrameworkCore packages to 2.1.0-preview1-final
In the same file, update the versions of the various <DotNetCliToolReference> elements for any Microsoft.VisualStudio, and Microsoft.EntityFrameworkCore packages to 2.1.0-preview1-final
In the same file, remove the <DotNetCliToolReference> elements for any Microsoft.AspNetCore packages. These have been replaced by global tools.

That should be enough to get the project building and running against 2.1.0-preview1. The following steps will change your project to use new code-based idioms that are recommended in 2.1

Open the Program.cs file
Rename the BuildWebHost method to CreateWebHostBuilder, change its return type to IWebHostBuilder, and remove the call to .Build() in its body
Update the call in Main to call the renamed CreateWebHostBuilder method like so: CreateWebHostBuilder(args).Build().Run();
Open the Startup.cs file
In the ConfigureServices method, change the call to add MVC services to set the compatibility version to 2.1 like so: services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
In the Configure method, add a call to add the HSTS middleware after the exception handler middleware: app.UseHsts();
Staying in the Configure method, add a call to add the HTTPS redirection middleware before the static files middleware: app.UseHttpsRedirection();
Open the project propery pages (right-mouse click on project in Visual Studio Solution Explorer and select “Properties”)
Open the “Debug” tab and in the IIS Express profile, check the “Enable SSL” checkbox and save the changes
Open the Properties/launchSettings.json file
In the "iisSettings"/"iisExpress" section, note the new property added to define HTTPS port for IIS Express to use, e.g. "sslPort": 44374
In the "profiles/IIS Express/environmentVariables" section, add a new property to flow the configured HTTPS port through to the application like so: "ASPNETCORE_HTTPS_PORT": "44374"
- This configuration value will be read by the HTTPS redirect middleware you added above to ensure non-HTTPS requests are redirected to the correct port. Make sure it matches the value configured for IIS Express.

Note that some projects might require more steps depending on the options selected when the project was created, or packages added since. You might like to try creating a new project targeting 2.1.0-preview1 (in Visual Studio or using dotnet new at the cmd line) with the same options to see what other things have changed.