What is a Package?

A package extends Umbraco to provide additional functionality to editors, developers, site visitors, and all other types of users of Umbraco. It can impact one or more of these groups of people depending on the type of package.

An Umbraco Package can be many things, but is generally characterized by:

• Adding or extending functionality in the Umbraco CMS

• Empowering people to do more and/or do things more efficiently

• Engaging community members in collaboration and sharing

• Solving real life problems

• Inspiring people on what Umbraco can be made capable of

Categories of packages

Packages provide a wide variety of functionality, and can often span multiple categories. In general, though, the functionality they provide fall into these main groups:

• Schema Extensions

• Management Extensions

• Starter Kits

• Content Apps

• Integration Extensions

Schema Extensions

A package that can be categorized as a Schema Extension will extend the default Umbraco Schema. Schema in this sense refers to things like Data Types, Property Editors, Document Types and Media Types. By extending Umbraco with packages such as Umbraco Commerce editors are given greater capabilities when they are populating their content pages.

Management Extensions

A Management Extension package helps you manage your site, and provides information to the users. Management extensions typically contain custom sections or dashboards to facilitate site management. Diplo God Mode is an example of a comprehensive management extension package with additional tools and information.

Starter Kits

Starter kits are, as the name suggests, a package that helps you set up a starter version of whatever you want to build. Most starter kit packages are for starting a website, and include schema like Document Types and Templates as well as content nodes and media. There are also some specialized starter kits, for example for creating a blog. Umbraco HQ has released their own starter kit, that creates a small site with the most commonly used features.

Content Apps

Content apps are almost like dashboards for content nodes that are intended to display node specific information. A good example of this is the Preflight content app. It shows you readability scores for your written content, directly on each content node.

Integration extensions

This type of package can be a lot of things, and can include a number of the other package types. They are generally integrating a larger system into Umbraco. A good example could be an e-commerce package such as UCommerce, that includes an entire webshop module for Umbraco.

Types of Packages

Packages for Umbraco 10 and above are installed as NuGet packages.

Creating a Package

This short tutorial will teach you how to create a package in the Umbraco backoffice. It will also give a quick overview of what a generated package will contain.

Language file for packages

Package authors who would like their UI to be multi-lingual can include their own set of language files as part of their package distribution.

Listing a Package on the Umbraco Marketplace

Once you've created a package make it available on the Umbraco Marketplace to share it with the community.

Packages on Umbraco Cloud

Things you should know if you are developing for Umbraco Cloud.

Maintaining Packages

Some guidance on how to maintain your package after release.

An Example Package 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.

If you are looking for inspiration to follow form some tried and tested packages, read more here.

Umbraco Core includes language files, but package authors must provide their own for multi-lingual UI.

Including new language keys

For each language your package supports, you include an .xml file in the same format as the core language files, named with its language code. The language files must be located in a Lang folder inside your package folder in App_Plugins. If your package assets are in /App_Plugins/mypackage all language files must be placed in the following locations:

• English keys: /App_Plugins/mypackage/Lang/en-US.xml

• Danish keys: /App_Plugins/mypackage/Lang/da-DK.xml

Language file format

Each language file can include one or more area. Each area contains a collection of language keys with the translation.

For reference on the language file format see the core

Sample structure

Packages for Umbraco 10 and above are installed as NuGet packages.

NuGet Packages

A NuGet package is a standard way of delivering compiled code and configuration to a .NET project. NuGet packages contain dll-files and other files required for the solution. For more information on NuGet packages see Microsoft's documentation.

NuGet packages can be installed using via the command line or through Visual Studio using either the or the .

See below, for an example of installing a package using the Package Manager Console in Visual Studio:

NuGet packages can include any solution files and can be configured to run PowerShell scripts after installation.

As NuGet packages are installed outside of the Umbraco website they cannot directly manipulate any of the Umbraco settings or content during their installation.

When adding or changing configuration of Umbraco as part of a NuGet package you need to develop code to run as part of a . The Migration will run the first time the Umbraco site starts after the package is installed, applying the correct configuration.

Package zip files

A package zip file can be installed directly through the Umbraco backoffice.

Packages zip files can contain:

• Content

• Solutions files (dlls, App_Plugins files, etc)

• Document Types

• Templates

• Stylesheets

• Macros

• Languages

• Dictionary Items

• Data Types

• Media

The is a website built and maintained by Umbraco HQ to support searching and reviewing packages.

It lists all commercial and open-source packages that the community has made available on NuGet.

More information, including details of the steps for listing, are available at the dedicated .

If you want to use or develop packages for Umbraco Cloud there are a few things to consider and be aware of. The two most important things to know about are

Storing data

When developing a package you will sometimes store data, this can be data in many forms - Umbraco schema / content, package settings, etc.

When you develop a package for Umbraco Cloud there are a few things to be aware of when storing data, mainly whether you want that data to be specific to 1 environment or more.

Let's take a look at the most common ways of storing data in packages - and what to watch out for on Cloud.

Migrations

A is some code that you run as part of a migration plan. That migration plan has an ID that is stored in the database (in the KeyValue table). This means that when you add new migrations Umbraco will only execute the ones that came after the one with the stored ID. The most important difference between a migration and a package action is when they are initialized. A package action runs on package install and uninstall, whereas a migration will run whenever you want it to run, see below for common examples.

As migration runs are stored in the database of the site it also means that they will run on each environment you trigger them on. The most common way to trigger a migration is to include them in a , which will ensure they run on site startup. This means any commands you have in your migration will automatically run when the site starts up. When your package code is pushed to a new environment it will run them from the beginning on that environment as no ID is saved in the database.

This is normally a good thing. However if you generate any Umbraco schema then Umbraco Deploy will automatically create based on that schema, and commit them to source control. This means that when you deploy all your files to the next environment the migration will run again, create duplicates and generate duplicate UDA files, which could end up causing a lot of issues.

You could consider creating Umbraco schema only during a package action, and then running things like creating database tables in migrations. Another good workaround could be to not run the migrations in a composer, but rather create a dashboard for the package where the user can choose which migrations to run themselves. The has an example of this.

Creating files

You may sometimes choose to save data in a file. Could be a separate config file for your package or a to add an app setting to the web.config. If you do this be aware of two things:

1. If these files are generated on a Cloud environment they will not be stored in source control, and will be overwritten on next deployment. They need to be installed locally, committed to source control and then pushed up to the Cloud environments. We have an on allowing package creators to commit their files directly on Cloud, and it is possible to do so currently but not in a supported way, and it may change suddenly.

2. If you need the content of the files to be different on the different environments you will need to use environment specific .

Value connectors

A value connector is an extension to Umbraco Deploy that allows you to transform data when you deploy content of any kind between environments. When it comes to packages, one reason you need to consider these if you are supporting deploying content properties that rely on integer IDs. Content and other Umbraco data has two identifiers - an integer and a GUID. The GUID is consistent between environments but the integer ID is not. As such, if transferring content between environments and relying on integer IDs, you'll need to include a value connector to transform the value.

They also manage dependencies for property data. If you save an ID of an image in your property editor, you can make sure the related image media item is transferred too.