3 Piles of round Umbraco stickers

Packages in Umbraco 9 via NuGet

Packages will be handled in a new way from Umbraco 9

Andy Butland
Written by Andy Butland

While working on the final bits for the Umbraco 9 release candidate, we came across a challenge related to package handling in Umbraco 9. Through discussions with both the Umbraco Package and Unicore community teams, we’ve come up with a solution: Packages in Umbraco 9 will have to be installed through NuGet. This might change the workflow for some, but since this is following best-practice in .Net 5/.NET Core, we see this as the only right and future-proof solution. In this blog post I’ll let you in on the reasons behind this decision and then you get to test the new package install workflow when the RC is out in mid-July: 

The issues

There are two main issues we’re facing regarding packages in Umbraco 9 - one immediate technical concern and one that’s been discussed many times over the years around best practices for installation and deployments.

Fighting the framework

The technical issue we have run into a few weeks back is around different behaviour between .NET Framework and .NET Core with regard to DLLs added at runtime. As you may know, installing a package with DLLs simply copies these files into the bin folder, and with .NET Framework, this causes a site restart, so they are picked up when the site comes back up.

This doesn’t work the same way in .NET 5/.NET Core. DLLs aren’t automatically picked up when added to a bin folder, and they don’t cause a restart. Because of the separation between web application and web server in .NET 5, there’s also no support for the application to trigger a restart itself.

We’ve been investigating technical solutions to this, but can only partially resolve the issue, and not in a clean way. DLLs can be loaded at runtime, but if they contain any services that should be registered in the IoC container, they can’t be added once the site has started up and hence won’t be available to components that depend on them. Restarts may be possible for certain web servers, but would rely on the web application “knowing” about the server - which is no longer always IIS - and could potentially cause file locking issues. Furthermore, the restart would lead to a short period with 503 responses, due to the way .NET Core boots. In .NET framework the application booted together with the first request. This is no longer the case.

In short, despite some clever minds considering this, there doesn’t seem to be a solution to this issue. And even if one was found, it would be rather hacky, and certainly be “fighting the framework” which expects there to be compile time dependencies for DLLs (i.e. installs from NuGet, or project references).

Installing assets and DLLs using best-practice 

The second, historical issue is around whether Umbraco should be promoting the practice of installing DLLs, views and client-side assets via the backoffice - potentially in a production site. As I expect many have discovered to their cost, this can be dangerous, as some packages won’t work without configuration, or might have colliding dependencies. And as the package reference hasn’t been added in source control, there’s a risk that it gets removed following the next deployment of the website.

As such, many developers avoid this approach completely, always installing via NuGet, and if that’s not available, manually extracting the installed DLLs and adding them as a reference from a “lib” folder.

How this will be handled in Umbraco 9

Given the issues described above, Umbraco 9 and onwards will only support NuGet installs for packages.

And what does this mean in practice? The “Packages'' section in the backoffice will remain, but you won’t be able to install packages directly from here. Replacing the install button will be the package specific dotnet CLI command, e.g. "dotnet add package Umbraco.Forms”

We'll continue to use our.umbraco.com data to feed the packages list in the backoffice but will be adding something to indicate which packages are Umbraco 9 compatible (as, of course, there won’t be a file to upload when creating or updating an Umbraco 9 with a version attached). We might be able to automate this at a later date. 

Mitigations to recognized downsides

Aside from not being able to install packages directly from the backoffice there are a few other downsides to making the NuGet approach the only first class citizen in Umbraco 9. 

Content Dependencies

One downside of this approach is the inclusion of Umbraco content and schema as part of an Umbraco package.

One approach to handling this is to use an Umbraco migration, and the Umbraco APIs, to create the necessary document types, data types and content that the package requires.

This requires more developer effort than simply selecting the items from the backoffice when generating the Umbraco package file. We plan to restore the ability to select items in a similar way and export them into a file that can be included within a NuGet package. On install of the package, and subsequent start-up of the site, Umbraco would recognize that these items need to be installed and would initiate that.

Starter Kits

Starter kits are currently handled in the same way as packages and are therefore affected by the same issues. We’re of the view that as the name suggests, these are one of the first things installed into a new Umbraco solution.

As creating a new site in Umbraco 9 now requires you to do use a dotnet new template via the CLI or Visual Studio - i.e. there will be no zip download of Umbraco 9 - requiring these to also be installed via a similar means isn’t adding any significant developer friction. So, starter kits will continue to be installed as packages and as indeed Umbraco 9 itself, via Visual Studio or the CLI. Furthermore, we think many starter kits might eventually become dotnet new templates instead of packages.

RC expected in mid-July

As mentioned in the intro, this challenge was discovered during the work on the Umbraco 9 Release Candidate. This means that we need a bit more time than initially announced in order to finish up the release. New expected release date for the RC is therefore mid-July 2021. 

But remember, unless you want to test package-installs, there is no need to wait to test Umbraco 9. The feature-complete beta is out now and we hope you’re up for helping us test so we can get that final polish until the big final release in August!

And if you want to get the latest Umbraco 9 updates, then make sure to catch the “Umbraco 9 - The next major version” talk on Thursday, June 10th, at Codegarden (sign-up is free), where Bjarke Berg and Elitsa Marinovska from Umbraco HQ will get you up to speed on everything Umbraco 9.

To sum up

Packages in Umbraco 9 will follow best-practice in .Net 5/.NET Core and installing via NuGet will be the only approach.

This was a tough decision as it changes the behavior and functionality of packages. Together with the Package and Unicore community teams, we have been thorough in looking at the possible solutions and feel that the proposed solution is in fact the right one and does bring benefits.

Changing workflows is always tricky - but in this case, necessary. We believe that this solution will continually improve the discoverability and ease of installation of different types of Umbraco packages in the future. 

You'll be able to test the package install and content/schema workflow in the Umbraco 9 release candidate in mid-July.

If you have any questions regarding this topic, please use the GitHub issue dedicated to this and we'll get back to you.


What do I need to be aware of when migrating a package to Umbraco 9?

The package will need to be available in a NuGet format for installation via Visual Studio or the CLI. Packages that only include client side assets can still be copied over and will be automatically picked up but this is a manual operation as there is currently no support for installing these via the Umbraco 9 backoffice. All publically distributed packages should be using NuGet.

Is there documentation for how to add my package to NuGet?

There is a dotnew template for creating packages for Umbraco 9, see the Package development section in the Umbraco 9/.NET Core documentation as well as a blog post series detailing the migration of a package to Umbraco 9.

Will I no longer be able to install Umbraco with a starter kit?

No, the starter kit installation step is no longer present in Umbraco 9. Adding a starter kit will be handled either via a dotnet new template or installed via NuGet.

Can I create content and/or schema packages from the backoffice?

Yes, as mentioned above we want to continue supporting the inclusion of content and schema in Umbraco packages. We are actively working on a solution that will allow you to select the items in the backoffice and include them for installation your NuGet package.

When will I be able to test the new package installation workflow? 

The package install and content/schema workflow will be available along with the release candidate in mid-July

Will I be able to install packages directly in Umbraco Cloud?

Due to the nature of the Umbraco Cloud infrastructure, this might be possible in the future. 

As we know and “own” the server and environment setup on Umbraco Cloud, this opens up the possibility for allowing installation of packages on behalf of the user. 

This is still an idea/work-in-progress, and we’ll bring an update once we know more about the possibilities in Umbraco Cloud regarding package installs. Thus, until further notice, package installs in Umbraco Cloud will work as described in the blog post above.

Will this prevent editors from installing packages?

Yes. As discussed, in some aspects at least, preventing editors from installing packages in production is a good thing; we avoid the risk of installing something that can’t be used without configuration and could potentially break the site.


Be the first to know when Umbraco 9 launches

The anticipated new version of Umbraco CMS is around the corner - a version that moves the CMS to the modern .NET 5/ASP.NET Core.

This is a huge milestone that paves the way for a better, faster and more modern Umbraco. We're super excited for the launch which is planned to take place just very soon! Sign up and be the first one to know! 

Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox