Example Package Repository

Suggestions for organizing and Umbraco package source code repository.

There are many ways to build and deploy your package to NuGet. You will likely have your own approach for organizing a solution and preferred tools for build and deployment.

It may be useful though to review some practices we share here, of how we build packages at Umbraco.

Some add-ons to the CMS created by Umbraco are closed-source, but we have some we make freely available with open-source repositories. An example is Umbraco.AuthorizedServices, that has a source code repository here on GitHub.

Solution Organization

The solution consists of three projects.

Package Project

The main package project lives in src/<ProjectName>. It contains in the project file a dependency on Umbraco CMS:

<PackageReference Include="Umbraco.Cms.Web.BackOffice" Version="[10.0, 14)" />

Here we provide an upper bound on the package. This ensures that developers can only install it into projects that are using versions of Umbraco that we have tested the package with.

When the next major version of Umbraco is released, we'll test and either extend the range or release a new version, as appropriate.

Tests Project

We have a project for unit tests in tests/<ProjectName>.Tests. It contains references to Umbraco.Cms.Tets and a project reference to the package:

<ProjectReference Include="..\..\src\Umbraco.AuthorizedServices\Umbraco.AuthorizedServices.csproj" />

Example Website

Finally there's an example Umbraco website that we use for manual testing of the package. It also has a project reference to the package project, allowing us to test updates as they are compiled.

Solution Items

As well as the projects, the following files are added to the solution:

Build and Deployment

We use AzureDevOps pipelines for continuous integration and releasing new versions of the package. The definition of how the project is built is defined in a .yaml file that's part of the source code repository.

The file can be found here.

Even if using another tool it may be worth reviewing how we have setup our pipeline. It may be you can setup something similar with your own provider.

Building the Package

The build consists of two stages: building the solution and running unit tests. Only if both succeed is the build as a whole considered successful.

Releasing the Package

We release the package manually in AzureDevOps, with a two stage process. Firstly we release to a "pre-releases" feed, and then after manual approval, to NuGet.

Last updated