Umbraco Unique Identifiers

Hello fellow Umbracians and welcome back to my garage!
As we lately had some talks internally about when to use what identifier when working with Umbraco entities I thought it would be nice to make a little overview about what identifiers there are and what usage they have.

Id

Let’s start with the most basic and widespread one.

This identifier is an integer value and is set when an entity is saved to the database. Every entity, be it content, templates or media, can be found by its Id.

When talking about the Id it is important to keep in mind that this is always only valid for one environment. For example Content Type on your local and development environment will have different Id’s even tough they are synced with e.g. uSync.

For that fact Id’s should never(!) be used as constants! Use the Key property instead!

Key

Thats also an identifier every Umbraco entity has.

It is a Guid value and will therefore always be unique.

The most important use case for this property is for syncing purposes over multiple environments. That means that your Content Type will have the same Key value on your local as well as on your development environment.

Alias

This is a little bit of a special identifier as only Content Types and Templates have it.

There can always be only one Content Type with a certain Alias. Same goes for Templates.

As with the Key, the Alias will also be synced across all your environments. So your Templates and Content Types will always have the same Alias.

UDI

Thats also a special case as the UDI is not a property but can be created by calling .GetUdi() on any Umbraco entity.

An UDI consists of three different parts and will look something like this: umb://media/4fed18d8c5e34d5e88cfff3a5b457bf2

The three parts are thirst the “umb://” which just says that this is an Umbraco entity. Secondly there comes the “media” which defines of which type the entity is, for every type there is a different identifier here like document or member. Lastly the comes the “4fed18d8c5e34d5e88cfff3a5b457bf2” which is the Key value of the entity minus its - characters.

As this identifier is based on the Key value of the entity it will also be the same across all your environments.

When to use which one?

If you need to make sure you are dealing with the same entity across multiple environments you can use the Key, Alias or UDI values as those will be synced.

For most other use cases it doesn’t really matter what you use.

Personally I prefer using the Key value when ever possible as it can make debugging across multiple environments somewhat easier.

Thanks for tuning in to another of my blog and see you next time!