Using Umbraco's Service APIs

Create and update entities in Umbraco from code.

Subscribing to Notifications

Subscribe to notifications to execute custom code on a number of operations.

Creating Forms

Create, submit and handle HTML forms with controllers.

Debugging your Umbraco site

Using Tracing and MiniProfiler to debug your code.

Source/Version Control

General advice on source controlling your Umbraco implementation.

During the development of your Umbraco site you can debug and profile the code you have written to analyse and discover bottlenecks in your code.

To perform proper debugging on your site you need to set your application to have debug enabled. This can be done by setting Umbraco:CMS:Hosting:Debug="true" for example in the appsettings.json file:

{
  "Umbraco": {
    "CMS": {
      "Hosting": {
        "Debug": true
      }
    }
  }
}

Tracing

Tracing and trace logging are two names for the same technique. You need to configure which log messages you want to log.

Enabling Trace Logging

We recommend at least logging the following namespace at minimum (Verbose) level to enable valuable trace logging:

{
  "Serilog": {
    "MinimumLevel": {
      "Override": {
        "Microsoft.AspNetCore.Mvc": "Verbose"
      }
    }
  }
}

The logged messages can as always be monitored in the log viewer in backoffice

MiniProfiler

Umbraco includes the Mini Profiler project in its core (see https://miniprofiler.com for more details). The MiniProfiler profiles your code method calls, giving you a greater insight into code duration and query time for (for example) underlying SQL queries. It's great for tracking down performance issues in your site's implementation.

Displaying the MiniProfiler

To display the profiler ensure that the configuration Umbraco:CMS:Hosting:Debug is set to true in the appSettings.json file. Thereafter you can add ?umbDebug=true to the query string of any request.

Also, ensure your template calls @Html.RenderProfiler() as one of the last things.

If you click 'Show Trivial' you can seen the kind of detail the MiniProfiler makes available to you about the execution path of your page:

and any underlying SQL Statements that are being executed for a part of the execution:

Writing to the MiniProfiler

If you feel like a part of your application is slow you can use the MiniProfiler in your code to test the speed of it.

All you have to do is inject the IProfiler interface and add a step around your logic:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ViewEngines;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.Controllers;

namespace MyCustomUmbracoProject
{
    public class RootController : RenderController
    {
        private readonly IProfiler _profiler;

        public RootController(
            IProfiler profiler,
            ILogger<RenderController> logger,
            ICompositeViewEngine compositeViewEngine,
            IUmbracoContextAccessor umbracoContextAccessor)
            : base(logger, compositeViewEngine, umbracoContextAccessor)
        {
            _profiler = profiler;
        }

        public override IActionResult Index()
        {
            // Perform a step
            using (_profiler.Step("Sleep"))
            {
                System.Threading.Thread.Sleep(1000);
            }

            return base.Index();
        }
    }
}

and now in the profiler you can see:

Umbraco Productivity Tool - Chrome Extension

If you are using the Google Chrome browser you can install this Umbraco Productivity Tool Chrome Extension.

This will allow you to quickly switch between debugging with the MiniProfiler, Trace viewer and normal mode.

Logging

Learn how Umbraco writes log files and how you can write to them.

Creating forms requires that you know your way around .NET Core MVC. So if you are familiar with adding view models, views and controllers you are ready to make your first form.

In this example we'll create a basic contact form containing a name, email and message field.

Creating the view model

First, we're going to create the model for the contact form by adding a new class to the /Models folder. If the folder doesn't already exist, create it at the root of your website. Let's call it ContactFormViewModel.cs

namespace MyFirstForm.Models
{
    public class ContactFormViewModel 
    {
        public string Name { get; set; }
        public string Email { get; set; }
        public string Message { get; set; }
    }
}

Build your solution after adding the model.

Creating the view

Next, we add the view for the form to the /View/Partials folder. Because we've added the model and built the solution we can add it as a strongly typed view.

Name your view "ContactForm".

The view can be built with standard MVC helpers:

@using MyFirstForm.Controllers
@model MyFirstForm.Models.ContactFormViewModel

@using (Html.BeginUmbracoForm<ContactFormController>(nameof(ContactFormController.Submit)))
{
    <div class="input-group">
        <label asp-for="Name"></label>
        <input asp-for="Name" />
    </div>
    <div>
        <label asp-for="Email"></label>
        <input asp-for="Email" />
    </div>
    <div>
        <label asp-for="Message"></label>
        <textarea asp-for="Message"></textarea>
    </div>
    <br/>
    <input type="submit" name="Submit" value="Submit" />
}

Adding the controller

Finally, we're going to add the controller. Create a new empty class in the /Controllers folder (if the folder doesn't already exist, create it at the root of the website). Name it ContactFormController and make it inherit from SurfaceController. Inheriting from SurfaceController requires that you call its base constructor. If you are using an IDE: Integrated Development Environment, this can be done automatically.

using Microsoft.AspNetCore.Mvc;
using MyFirstForm.Models;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Website.Controllers;

namespace MyFirstForm.Controllers
{
    public class ContactFormController : SurfaceController
    {
        public ContactFormController(
            IUmbracoContextAccessor umbracoContextAccessor,
            IUmbracoDatabaseFactory databaseFactory,
            ServiceContext services,
            AppCaches appCaches,
            IProfilingLogger profilingLogger,
            IPublishedUrlProvider publishedUrlProvider) 
            : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
        {}

        [HttpPost]
        public IActionResult Submit(ContactFormViewModel model)
        {
            if (!ModelState.IsValid)
            {
                return CurrentUmbracoPage();
            }
            
            // Work with form data here

            return RedirectToCurrentUmbracoPage();
        }
    }
}

If the model state is invalid, CurrentUmbracoPage() will send the user back to the form. If valid, you can work with the form data, for example, sending an email to site admin and then RedirectToCurrentUmbracoPage();.

Adding the form to a template

You can add the form to a template by rendering the partial view:

@using MyFirstForm.Models;

@{
    Html.RenderPartial("~/Views/Partials/ContactForm.cshtml", new ContactFormViewModel());
}

Adding the form through the backoffice

To add the form to your site we'll make a macro. This also makes it possible to let editors add the form to a page using the rich text editor.

Creating a macro

Go to the Settings section and right-click the Partial Views Macro Files node. Choose "Create" and select New partial view macro. Name the macro Contact Form.

In the partial view, we're going to render our contact form using the view model we created earlier.

@inherits Umbraco.Cms.Web.Common.Macros.PartialViewMacroPage;

@using MyFirstForm.Models;

@{
    Html.RenderPartial("~/Views/Partials/ContactForm.cshtml", new ContactFormViewModel());
}

Adding the macro

The last thing to do before we can add the form to a page is to allow the Macro in a rich text editor. Expand the Macros node and select the Contact Form Macro. Check the boxes under Editor Settings.

Now you can add the form to a page that has a rich text editor.

More information

• Surface Controllers

• Custom controllers

• Routing

Whenever you need to modify an entity that Umbraco stores in the database, there are a number of service APIs available to help you. This means that you can create, update and delete any of the core Umbraco entities directly from your custom code.

Accessing the Umbraco services

Services are typically defined using interfaces. Umbraco has them in the Umbraco.Cms.Core.Services namespace, while the specific implementations can be found under the Umbraco.Cms.Core.Services.Implement namespace. To use the service APIs you must first access them. Owing to the built-in dependency injection (DI) in ASP.NET Core, configured services are made available throughout Umbraco's codebase. This can be achieved via injecting the specific service you require - the service type or an interface.

Access via a Controller

If you are accessing Umbraco services inside your own controller class, you can add the Umbraco services that you need as constructor parameters. An instance of every service will be provided at runtime from the service container and by saving each one to a local field, you can make use of them within the scope of your class:

public class CustomController
{
    private readonly IContentService _contentService;


    public ContentController(IContentService contentService)
    {
        _contentService = contentService;
    }


    public ActionResult PerformAction()
    {
        var someContent = _contentService.GetById(1234);
    }
}

Access via a Razor View Template

Inside a Razor View template, you can make use of a service injection into a view using the @inject directive. It works similarly to adding a property to the view, and populating the property using DI:

@using Umbraco.Cms.Core.Services
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@inject IPublicAccessService PublicAccessService
@{
    Layout = "master.cshtml";
    bool isPageProtected = PublicAccessService.IsProtected(Model.Path);
}
@if (isPageProtected)
{
    <h1>Secret Page - shhshshsh!</h1>
}

Access in a Custom Class via dependency injection

If for instance we wish to subscribe to notifications on one of the services, we'd do so in a Composer C# class, where you will add a custom NotificationHandler. In this custom NotificationHandler we would inject the service we need into the public constructor of the class and Umbraco's underlying dependency injection framework will do the rest.

In this example we will wire up to the ContentService 'Saved' event, and create a new folder in the Media section whenever a new LandingPage is created in the content section to store associated media. Therefore we will need the MediaService available to create the new folder.

public class CustomComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationHandler<ContentSavedNotification, CustomNotificationHandler>();
    }
}

using System.Linq;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;

namespace Umbraco.Cms.Core.Events
{
    public class CustomNotificationHandler : INotificationHandler<ContentSavedNotification>
    {
        // access to the MediaService by injection
        private readonly IMediaService _mediaService;
        private readonly IRuntimeState _runtimeState;

        public CustomNotificationHandler(IMediaService mediaService, IRuntimeState runtimeState)
        {
            _mediaService = mediaService;
            _runtimeState = runtimeState;
        }

        public void Handle(ContentSavedNotification notification)
        {
            if (_runtimeState.Level != RuntimeLevel.Run)
            {
                return;
            }

            foreach (var contentItem in notification.SavedEntities)
            {
                // if this is a new landing page create a folder for associated media in the media section
                if (contentItem.ContentType.Alias == "landingPage")
                {
                    // we have injected in the mediaService in the constructor for the component see above.
                    bool hasExistingFolder = _mediaService.GetByLevel(1).Any(f => f.Name == contentItem.Name);
                    if (!hasExistingFolder)
                    {
                        // let's create one (-1 indicates the root of the media section)
                        IMedia newFolder = _mediaService.CreateMedia(contentItem.Name, -1, "Folder");
                        _mediaService.Save(newFolder);
                    }
                }
            }
        }
    }
}

Custom Class example

When you are creating your own custom class, in order to make use of the dependency injection framework, you need to register the ICustomNewsArticleService service with the concrete type CustomNewsArticleService. The AddScoped() method registers the service with the lifetime of a single request.

There are several different ways that you can achieve the same outcome:

Register directly into the Startup.cs class.

using Microsoft.Extensions.DependencyInjection;

namespace DefaultNamespace
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {   
            services.AddScoped<ICustomNewsArticleService, CustomNewsArticleService>();
        }
    }
}

Another approach is to create an extension method to IUmbracoBuilder and add it to the startup pipeline.

using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.DependencyInjection;

namespace DefaultNamespace
{
    public static class UmbracoBuilderServiceExtensions
    {
        public static IUmbracoBuilder AddCustomServices(this IUmbracoBuilder builder)
        {
            builder.Services.AddScoped<ICustomNewsArticleService, CustomNewsArticleService>();
            
            return builder;
        }
    }
}

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Extensions;

namespace DefaultNamespace
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddUmbraco(_env, _config)
                .AddBackOffice()             
                .AddWebsite()
                .AddComposers()
                .AddCustomServices()
                .Build();
        }
    }
}

Especially recommended when creating Umbraco packages as you won't have access to the Startup class, instead you can achieve the same as above by using a custom Composer which gives you access to the IUmbracoBuilder.

public class CustomComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddScoped<ICustomNewsArticleService, CustomNewsArticleService>();
    }
}

Then your custom class eg. CustomNewsArticleService can take advantage of the same injection to access services eg:

using System.Linq;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PublishedCache;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;

namespace Umbraco.Cms.Infrastructure.Services.Implement
{
    public class CustomNewsArticleService: ICustomNewsArticleService
    {
        private readonly IMediaService _mediaService;
        private readonly ILogger<CustomNewsArticleService> _logger;
        private readonly IUmbracoContextFactory _contextFactory;

        public CustomNewsArticleService(ILogger<CustomNewsArticleService> logger, IUmbracoContextFactory contextFactory, IMediaService mediaService)
        {
            _logger = logger;
            _contextFactory = contextFactory;
            _mediaService = mediaService;
        }

        public void DoSomethingWithNewsArticles()
        {
            using (var contextReference = _contextFactory.EnsureUmbracoContext())
            {
                IPublishedContentCache contentCache = contextReference.UmbracoContext.Content;
                IPublishedContent newsSection = contentCache.GetAtRoot().FirstOrDefault().Children.FirstOrDefault(f => f.ContentType.Alias == "newsSection");
                if (newsSection == null)
                {
                    _logger.LogDebug("News Section Not Found");
                }
            }
            // etc
        }
    }
}

Services available

There is full API coverage of all Umbraco core entities:

• AuditService

• ConsentService

• ContentService

• ContentTypeService

• DataTypeService

• EntityService

• FileService

• LocalizationService

• MacroService

• MediaService

• MemberService

• MemberTypeService

• MemberGroupService

More information

• Umbraco Services API reference

• Umbraco Notifications reference

• Routes and controllers

Subscribing to notifications allows you to execute custom code on a number of operations both before and after the operation occurs. All you need to follow this guide is an Umbraco installation with some content, e.g. the Umbraco starter kit.

Subscribing to a notification

Let's add a string of text to the log when a document is published. (The log is useful for debugging, different parts of the Umbraco codebase 'log' key events, warnings and errors to the log)

We react to notifications in Umbraco inside a notification handler, so let's create one. Add a new C# class to our project - call it LogWhenPublishedHandler and use : INotificationHandler<ContentPublishedNotification> to identify our code as a handler, that will handle ContentPublishedNotification. We'll need to add using Umbraco.Cms.Core.Events; to the top of the .cs file and because the notifications that you can subscribe to in Umbraco are found in the core notifications namespace, we also need to add a using statement for that: using Umbraco.Cms.Core.Notifications;.

We now have a class that looks like this:

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MyProject
{
    public class LogWhenPublishedHandler : INotificationHandler<ContentPublishedNotification>
    {
        // Here we'll handle a notification.
    }
}

However, we have an error and a red squiggly line under our class, this is because the INotificationHandler interface expects us to implement a Handle method for our notification. Let's create a public method called Handle that takes a ContentPublishedNotification as a parameter:

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MyProject
{
    public class LogWhenPublishedHandler : INotificationHandler<ContentPublishedNotification>
    {
        public void Handle(ContentPublishedNotification notification)
        {
            // The custom code to fire every time content is published goes here!
            throw new System.NotImplementedException();
        }
    }
}

To check that this works, let's add a message to the log every time a content node is published.

We'll need to inject a Microsoft ILogger into our notification handler, by adding using Microsoft.Extensions.Logging; to the top our file to add the required namespace, and creating a constructor for our handler that allows Umbraco to inject the logger:

using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MyProject
{
    public class LogWhenPublishedHandler : INotificationHandler<ContentPublishedNotification>
    {
        private readonly ILogger<LogWhenPublishedHandler> _logger;

        public LogWhenPublishedHandler(ILogger<LogWhenPublishedHandler> logger)
        {
            _logger = logger;
        }
        
        public void Handle(ContentPublishedNotification notification)
        {
            // The custom code to fire every time content is published goes here!
            throw new System.NotImplementedException();
        }
    }
}

Now we can use the logger to send a message to the logs:

public void Handle(ContentPublishedNotification notification)
{
    // The custom code to fire every time content is published goes here!
    _logger.LogInformation("Something has been published.");
}

We could log the name of each item that is being published too:

public void Handle(ContentPublishedNotification notification)
{
    // The custom code to fire every time content is published goes here!
    _logger.LogInformation("Something has been published.");
    foreach (var publishedItem in notification.PublishedEntities)
    {
        _logger.LogInformation("{ContentName} was published", publishedItem.Name);
    }
}

Now we have a notification handler that logs the name of a piece of content every time it's published, however, we're not done yet.

Umbraco needs to know that our handler exists and that it handles ContentPublishedNotification, to tell Umbraco this, we open up the Startup.cs file in the root of the project. First, we need to add using Umbraco.Cms.Core.Notifications; to the top of this file as well, once we've done this we need to find the ConfigureServices method. We now add .AddNotificationHandler<ContentPublishedNotification, LogWhenPublishedHandler>() to the ConfigureServices method right before the Build() part. The method now looks like this:

        public void ConfigureServices(IServiceCollection services)
        {
#pragma warning disable IDE0022 // Use expression body for methods
            services.AddUmbraco(_env, _config)
                .AddBackOffice()             
                .AddWebsite()
                .AddComposers()
                .AddNotificationHandler<ContentPublishedNotification, LogWhenPublishedHandler>()
                .Build();
#pragma warning restore IDE0022 // Use expression body for methods

        }

The entire handler class should look like this:

using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace MyProject
{
    public class LogWhenPublishedHandler : INotificationHandler<ContentPublishedNotification>
    {
        private readonly ILogger<LogWhenPublishedHandler> _logger;

        public LogWhenPublishedHandler(ILogger<LogWhenPublishedHandler> logger)
        {
            _logger = logger;
        }
        
        public void Handle(ContentPublishedNotification notification)
        {
            // The custom code to fire every time content is published goes here!
            _logger.LogInformation("Something has been published.");
            foreach (var publishedItem in notification.PublishedEntities)
            {
                _logger.LogInformation("{ContentName} was published", publishedItem.Name);
            }
        }
    }
}

Now we're ready to spin up our site and give it a try. Go to the Umbraco backoffice and publish a piece of content. Switch to the Settings section and find the Log Viewer in the Settings tree:

Search 'All Logs', and if all is wired up correctly you should discover your custom publish log message entries:

Before and after

As you can see our custom code has been executed when we published a piece of content. It executed after the item was published because we used the ContentPublishedNotification. If you want to run code before publishing, use ContentPublishingNotification. The same goes for most other notifications so Saving : Saved, Copying : Copied and so forth.

More information

• Notifications Reference

Umbraco Cloud

When you are running your site on Umbraco Cloud, source control is a part of the experience. Have a look at the 'Technical overview of an Umbraco Cloud Environment' and the information on 'Working with your Umbraco Cloud project' for a steer on Source/Version Control good practices.

Outside of Umbraco Cloud

If you are hosting your Umbraco implementation outside of Umbraco Cloud, it's generally considered good practice to set up source/version control for your site implementation files. This is especially a good idea when you are working with a team as it can help you track changes and manage conflicts with other developer's work.

So if you've made the decision to try to attempt to source/version control your Umbraco implementation work, perhaps setting up a 'Git Repository' - then a frequently asked question is:

What folders and files should I exclude from my source control repository?

There are lots of different possible variations within your working environment that will affect the best way to set up version control. It depends on whether you are:

• Working with a team of developers.

• How your development environment is set up.

• Source control repository.

• And also how you intend to build and deploy your solution to your target production environment (build servers, Web Deploy or good old File Transfer Protocol (FTP), etc).

However, Umbraco ships with a .gitignore file with a custom Umbraco section, which will make git ignore the files for you. The Umbraco specific section looks like this:

##
## Umbraco CMS
##

# JSON schema file for appsettings.json
appsettings-schema.json

# Packages created from the backoffice (package.xml/package.zip)
/umbraco/Data/CreatedPackages/

# Temp folder containing Examine indexes, NuCache, MediaCache, etc.
/umbraco/Data/TEMP/

# SQLite database files
/umbraco/Data/*.sqlite.db
/umbraco/Data/*.sqlite.db-shm
/umbraco/Data/*.sqlite.db-wal

# Log files
/umbraco/Logs/

# Media files
/wwwroot/media/

##
## Umbraco CMS .NETCore
##

# Don't commit Umbraco TEMP folder containing Examine Indexes, NuCache etc
**/umbraco/Data/TEMP/

# Don't commit files that are generated and cached from the default ImageSharp location
**/umbraco/mediacache/

# Umbraco backoffice language files
# Nuget package Umbraco.Cms.StaticAssets will copy them in during dotnet build
# Customize language files in /config/lang/{language}.user.xml
**/umbraco/config/lang/

# JSON Schema file for appsettings
# This is auto generated from the build
**/umbraco/config/appsettings-schema.json

# This is the no-nodes, installer & upgrader pages from Umbraco
# Nuget package Umbraco.Cms.StaticAssets will copy them in during dotnet build
**/umbraco/UmbracoWebsite/
**/umbraco/UmbracoInstall/
**/umbraco/UmbracoBackOffice/

# Comment out the line below if you wish to change or add any new templates to PartialView Macros
**/umbraco/PartialViewMacros/

# Umbraco Static Assets of Backoffice
# Nuget package Umbraco.Cms.StaticAssets will copy them in during dotnet build
**/wwwroot/umbraco/

For most projects, this gitignore will be enough, and this article will not be an exhaustive list of how to version control Umbraco in all possible scenarios.

However, we will go through the different files in order to give you an insight into the anatomy of an Umbraco website and therefore which parts to include in version control and which parts not to.

The Umbraco Folder

Umbraco Models Builder

The strategy here will depend a little on which mode 'Umbraco Models Builder' you have opted to work with.

• InMemoryAuto (default), The models are generated in memory, no source control is required.

• SourceCodeManual and SourceCodeAuto, The models are generated in the /umbraco/models folder of your project (or can be configured to be in a different folder or project), allowing you to track changes to the models in source/version control.

Media

The Media section of Umbraco (unless configured otherwise) stores files in the /wwwroot/media folder. These can be updated by editors, in the Umbraco backoffice, so generally speaking, you would not source control these files.

These are by default ignored by git.

Packages and Plugins

The App_Plugins folder is the home for all third-party packages installed on your site.

Depending on how you installed the plugin it will affect how you choose to version control a particular third-party plugin:

Since plugins are installed via NuGet the installed files for individual plugins shouldn't need to be source controlled (and your deployment process should pull the packages implementation files from NuGet during the build and deployment process).

What folders and files should I include in my source control repository?

Front-end build

A lot depends on how you maintain the front-end build of your website, e.g. are you using CSS preprocessors such as Sassy Cascading Style Sheets (SCSS)/ Leaner CSS (LESS) etc - gulp/grunt tasks to combine and minify script resources.

But generally, you will need to source control all your website's static assets: JavaScript, CSS, Fonts, Page Furniture Images, etc.

Views/Templates/Partials

Umbraco site templates/views can be edited via the Umbraco Backoffice. They also reside in the /Views folder on disk. As these views/templates often include code, it can make a lot of sense to have their changes tracked under source/version control.

However, this can pose a problem if the templates are updated via the backoffice outside of source control on the production environment.

This is not an advisable approach since often this will cause breaking changes to your website.

You would need to manually merge these files before considering a deployment.

Umbraco Cloud is a good solution in these scenarios, as changes via the backoffice are tracked in a Git repository automatically.

Macros

To source/version control changes to Macro implementation code, track the files in the following location:

• Partial View Macros - stored in /Views/MacroPartials as .cshtml files

Controllers/Classes/Custom Code

Any supporting custom code for your application should be in version control, eg any of the following files

• C# implementation,

  • Surface Controllers

  • API Controllers

  • ViewModels

  • Helpers / Extension Methods

  • Services etc.

• Supporting class library projects,

• Models generated by Modelsbuilder in SourceCodeManual or SourceCodeAuto mode.

Config

Your site's appsettings.json and appsettings.Development.json files contain the configuration for your Umbraco site.

In general, it is recommended to add these to source control. When you do this, be sure that the file(s) doesn't contain any secrets, like API keys and connection strings. These can be added as needed, but omitted from any commits made to source control.

DocumentType - Backoffice Structure Changes

When you create and edit eg. Document Types, Media Types, and Data Types in the Umbraco Backoffice these values are stored in the Umbraco Database, making them difficult to source control in a 'file based' version control system.

There are a series of add-on packages that can help add source control to these structure changes:

• The uSync package (free) - which can be configured to serialize these changes to files on disk, in a folder called /uSync - enabling you to source/version control these changes and synchronise them to other environments.

• uSync Snapshots (licensed) - an extension to uSync, for taking 'before' and 'after' snapshots of an Umbraco site, for managing a release of a 'set of changes' between environments.

• Umbraco Deploy on Premise - the on premise version of the package used by Umbraco Cloud.

In Umbraco we use the underlying logging framework of Serilog.

Out of the box, we write a JSON log file that contains a more detailed logfile. This allows tools to perform searches and correlations on log patterns more efficiently.

The default location of this file is written to umbraco/Logs and contains the Machine name, along with the date too:

• umbraco/Logs/UmbracoTraceLog.DELLBOOK.20210809.json

Structured logging

Serilog is a logging framework that allows us to do structured logging or write log messages using the message template format. This allows us to have a more detailed log message, rather than the traditional text message in a long txt file.

2021-08-10 09:33:23,677 [P25776/D1/T22] INFO   Umbraco.Cms.Core.Services.Implement.ContentService - Document Home (id=1062) has been published.

Here is an example of the same log message represented as JSON. More information is available and allows you to search and filter logs based on these properties with an appropriate logging system.

{
  "@t":"2021-08-10T08:33:23.6778640Z",
  "@mt":"Document {ContentName} (id={ContentId}) has been published.",
  "ContentName":"Home",
  "ContentId":1062,
  "SourceContext":"Umbraco.Cms.Core.Services.Implement.ContentService",
  "ActionId":"7726d745-d502-4b2d-b55e-97731308041b",
  "ActionName":"Umbraco.Cms.Web.BackOffice.Controllers.ContentController.PostSave (Umbraco.Web.BackOffice)",
  "RequestId":"8000000c-0012-fb00-b63f-84710c7967bb",
  "RequestPath":"/umbraco/backoffice/umbracoapi/content/PostSave",
  "ProcessId":25776,
  "ProcessName":"iisexpress",
  "ThreadId":22,
  "AppDomainId":1,
  "AppDomainAppId":"2f4961977e5c252fa708f7d83915c269b53a620c",
  "MachineName":"DELLBOOK",
  "Log4NetLevel":"INFO ",
  "HttpRequestId":"318b6dd4-b127-4da3-8339-37701f4d1416",
  "HttpRequestNumber":4,
  "HttpSessionId":"0cea7395-ba29-e6c6-93ee-7c08a2fd7219"
}

To learn more about structured logging and message templates you can read more about it over on the https://messagetemplates.org website. Alternatively watch this video from the Serilog creator - https://www.youtube.com/watch?v=OhmNp8UPEEg

Writing to the log

Umbraco writes log messages, but you are also able to use the Umbraco logger to write the log file as needed. This allows you to gain further insights and details about your implementation.

Here is an example of using the logger to write an Information message to the log. It will contain one property, Name, which will output the name variable that is passed into the method.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Web.Common.Controllers;

namespace Umbraco.Cms.Web.UI.NetCore
{
    public class MyApiController : UmbracoApiController
    {
        private readonly ILogger<MyApiController> _logger;

        public MyApiController(ILogger<MyApiController> logger)
        {
            _logger = logger;
        }

        /// /umbraco/api/MyApi/SayHello?name=John
        [HttpGet]
        public string SayHello(string name)
        {
            _logger.LogInformation("We are saying hello to {Name}", name);
            return $"Hello {name}";
        }
    }
}

The incorrect way to log the message would be use string interpolation or string concatenation such as

//GOOD - Do use :)
_logger.LogInformation("We are saying hello to {Name}", name);

//BAD - Do not use :(
_logger.LogInformation($"We are saying hello to {name}");

//BAD - Do not use :(
_logger.LogInformation("We are saying hello to " + name);

The bad examples above will write to the log file, but we will not get a separate property logged with the message. This means we can't find them by searching for log messages that use the message template We are saying hello to {Name}

Log Levels

Serilog uses levels as the primary means for assigning importance to log events. The levels in increasing order of importance are:

1. Verbose - tracing information and debugging minutiae; generally only switched on in unusual situations

2. Debug - internal control flow and diagnostic state dumps to facilitate pinpointing of recognised problems

3. Information - events of interest or that have relevance to outside observers; the default enabled minimum logging level

4. Warning - indicators of possible issues or service/functionality degradation

5. Error - indicating a failure within the application or connected system

6. Fatal - critical errors causing complete failure of the application

Configuration

Serilog can be configured and extended by using the .NET Core configuration such as the AppSetting.json files or environment variables. For more information, see the Serilog config article.

The logviewer dashboard

Learn more about the logviewer dashboard in the backoffice and how it can be extended.

The logviewer desktop app

This is a tool for viewing & querying JSON log files from disk in the same way as the built in log viewer dashboard.

Serilog project/references shipped

Umbraco ships with the following Serilog projects, where you can find further information & details with the GitHub readme files as needed.

• Serilog

• Serilog.AspNetCore

• Serilog.Enrichers.Process

• Serilog.Enrichers.Thread

• Serilog.Expressions

• Serilog.Formatting.Compact

• Serilog.Formatting.Compact.Reader

• Serilog.Settings.Configuration

• Serilog.Sinks.Console

• Serilog.Sinks.File

Further Resources

If you are interested in learning more then the following resources will beneficial:

• Serilog

• Serilog Community Gitter Chatroom

• Nicholas Blumhardt Blog, creator of Serilog

• Serilog Pluralsight Course

• Seq This is free for a single machine such as your own local development computer