Status of migration to .NET Core

Update September 3rd 2020: Umbraco .NET Core Alpha has been released and is now available for testing.

ASP.NET Core

First, let’s talk about ASP.NET Core - the web framework of .NET Core. This is actually the part that has changed the most compared to the current version of Umbraco, that uses ASP.NET.

The good thing for Umbraco customers is that the most changed parts are actually handled by Umbraco. These changes are mainly the request pipeline, HttpContext, Configuration and the fact that MVC and WebApi are now combined into a single framework - MVC.

The benefit of using ASP.NET Core compared to ASP.NET is mainly new features and testability.

Luckily, ASP.NET Core is not completely different from what we already use. The key part: MVC - Models, Views and Controllers are highly recognisable. 

 

What’s changed so far

So far, the changes made to the code base are mostly to make the internal libraries compatible with .NET Core.

Let’s start by taking a look at the architecture:

All assemblies are today .NET Framework 4.8. To move them into .NET Standard, we need to remove all third-party dependencies that are not compatible. The biggest issue here is the usage of ASP.NET (System.Web) is known in all of the Umbraco assemblies.

To avoid using ASP.NET directly in all of the Umbraco assemblies, we have introduced a series of abstractions, like IRequestCache, ICookieManager, ISessionManager, IHostingEnvironment, etc.

This method is generally used for all third party dependencies that are not compatible with .NET Standard.

The current status of the architecture is illustrated in the following diagram:

It is quite clear to see that we are currently between two chairs. We now have two executables - the existing one for .NET Framework and a new one for .NET Core. The .NET Core one is entirely new, and currently only returns “Hello world” for each request. 

The most exciting part is that most of the libraries are actually compatible with .NET Core now. We still have some functionality left in Umbraco.Web that needs to be migrated, before we can start migrating the actual backoffice functionality, like Models, Controllers and Views.

Also, note that we have separated the Umbraco.Core assembly into two Umbraco.Core and Umbraco.Infrastructure. The difference is that Umbraco.Core cannot have any third-party dependencies, Umbraco.Infrastructure can.

 

Breaking changes

We can’t completely avoid breaking changes, but we do whatever we can to avoid unnecessary breaking changes. By using this strategy, it makes it easier to migrate, and for ourselves, it becomes easier to merge features developed on Umbraco 8 into this version.

You can expect that most constructors of service, repositories and other non-model classes have changed. Even though this is a big breaking change, it should mainly be handled by the dependency injection container.

You also can expect a series of new interfaces that should be used instead of using static classes. So in the future, inject IIOHelper instead of using IOHelper, Inject IHostingEnvironment instead of using the static HostingEnvironment, and so forth.

The last area we expect to introduce breaking changes in is Configuration. The pattern used to get configuration has changed between ASP.NET and ASP.NET Core. Instead of transforming each configuration file, the new way of doing things is to read from multiple sources. E.g.

1. Read from a general configuration file
2. Read from an environment-specific configuration file
3. Read from environment variables

We plan to align with ASP.NET Core as much as possible, and we, therefore, intend to use the new configuration pattern. This will also mean that configuration files in the future will be changed from XML to JSON.

 

Areas not changed

I know that database changes is a topic that many are worried about. I want to confirm that we don't expect to introduce more changes to the database structure, than what happens between minor versions.

Furthermore, this project is about .NET Core, so we are not changing more of the Javascript than absolutely needed. I only expect changes to the users' and members' parts of the javascript code, due to the updates to ASP.NET Core Identity from ASP.NET Identity and MembershipProviders, respectively.

Overall we expect the web API used by backoffice to remain as it is today.

The last part that we expect can be reused in general, are the views. Unless you have a lot of business logic in your views. In that case, you will most likely need to inject the dependencies.

 

Availability

Before we can talk about availability, it makes sense to start with some definitions:

Milestone 1

• Backoffice is running on .NET Core
• Not a feature-complete backoffice
• Missing members integrations
• Missing NuGet packages
• Expect still undocumented breaking changes 

 

Milestone 2

• Backoffice and Website running on .NET Core
• Expect few, but documented breaking changes
• Package development is expected to begin

 

Milestone 3

• HQ packages available
• StarterKit
• Forms
• Deploy

 

We expect to have Milestone 1 available in the second half of 2020, and we aim to reach milestone 2 in 2020. Milestone 3 is expected in the first half of 2021. Note that this is based on the current trajectory and can change depending on the amount of community involvement, findings etc.

We still don’t have any information about the final release.

 

Community involvement

Community involvement is really important for us on this project. Hence we have created a community team at the beginning of the year and they have already done stellar work both in terms of contributions and helping us validate and adjust the approach. You can read more about the team here.

In general, we are doing whatever we can to find tasks that make sense as up-for-grabs. But for the time being, most tasks have tight deadlines.

But we also need your involvement in other parts. Feedback is especially welcome on the request-for-comments we opened. Currently, we are discussing the installation process for Umbraco.

Finally, when we reach the milestones mentioned, we would love to have you try it out. If you find anything that does not work, please let us know by reporting it as an issue on GitHub.

 

Progress update (July 2020)

Since writing this blog post, the progress on migrating Umbraco to .NET core has continued at a very good pace. Here's some updated information on the progress since this blog post was published.

 

.NET Core projects on the roadmap as of 26/06/2020

Below are the .NET Core projects on our roadmap (see full roadmap here) when it was last updated on 26/06/2020:

Now

All Libraries Compatible

Umbraco source code solution is re-structured and everything is .NET Core compatible. This first phase in the transition to .NET Core provides a cleaner architecture and makes it easier to work with and contribute to Umbraco. For detailed information information see the Project Structure for Project UniCore RFC.

Backoffice Operational

Backoffice is fully operational on .NET Core. We can build a version that can be end-to-end tested for content management. The plan is to make an alpha release once we reach this milestone.

Expected release: Umbraco .NET Core Alpha has been released

Next

Frontend Rendering

Content can be queried and rendered in views. With this ready we can release a beta build and implementers/frontend developers can start using and testing the .NET Core. This milestone should produce a beta build.

Later

Ready for Package Development

Umbraco CMS is running on .NET Core and we can start focusing on the add-ons and packages that will need to be upgraded such Umbraco Forms and Deploy. At this stage we want to get the first release candidate out and this is also the perfect time for package developers to test their package on this new version.

 

Product updates relating to .NET Core

Every few weeks we share an overall product update across all Umbraco products. Below are the product updates where we've given an update on the .NET Core progress.

Product Update - May 1st 2020

... Another big project that’s moving along according to the plan is the .NET Core upgrade for Umbraco CMS. With great collaboration from both community and partners, this project is making solid progress. Bjarke Berg, the man in charge of the project at Umbraco HQ, will keep you updated on the project ...

Read the full product update

Product Update - June 12th 2020

... While we prepare for the next release of Umbraco CMS (8.7) including the new block editor (see the previous Product Update) I wanted to bring your attention to the .NET Core development of Umbraco. This project is moving forward as planned and we currently expect to bring an Alpha release to you in Q3 where you can get your first hands-on experience with a backoffice running .NET Core.

If you would like to be part of this project, get in touch with Bjarke and the .NET core community team who are leading the project. 

If you are ready to jump into code, I’ve got good news for you! There are several options available on GitHub where there’s also a brand new migration task waiting for some action. ...

Read the full product update