UmbraCare LOGO

Storing custom configuration in the Umbraco database

You will learn how to store custom settings in the Umbraco database without the need to create a new table.

Published on: , by:
Wojciech Tengler picture
Wojciech Tengler
Piotr Bach picture
Piotr Bach
Umbraco

Jump to Section

Introduction to Storing Custom Configurations in Umbraco#

As a developer, you have probably encountered a situation in which you had to store a setting in the database.

In such a situation, an additional table is required. 

Of course, you can connect to the database on each environment and create a new table using a basic script.

If you want to do it more elegantly, you need to create a migration so the table will be created automatically if it is missing during the Umbraco startup.

This requires additional work, which could be time-consuming.

Leveraging Existing Tables for Custom Configurations#

Happily, there is a way to store a simple configuration values in the existing umbracoKeyValue table.

This table consists of three columns: key, value, and updated.

Umbraco umbracoKeyValue table in SQL Server Management Studio view

Umbraco umbracoKeyValue table in SQL Server Management Studio view

Please be aware that the value column is of type nvarchar(255), so it has some limitations.

Efficiently Using the umbracoKeyValue Table for Settings#

Of course, we can use existing KeyValue class and store new rows as below:

using (var scope = _scopeProvider.CreateScope())
{
    scope.Database.InsertOrUpdate(new KeyValue { Identifier = "MyKey", Value = "MyValue", UpdateDate = DateTime.Now });

    scope.Complete();
}

Simplifying the Process with IKeyValueService#

However, an API is available, and we don't need to inject IScopeProvider to access the Umbraco database.

All we need to do is inject the available IKeyValueService.

Then, we can use the existing SetValue method as below:

_keyValueService.SetValue("MyKey", "MyValue");

To retrieve an existing value, we just need to use other available method:

_keyValueService.GetValue("MyKey");

We can find other interesting methods which could be useful in some scenarios. Here is a full list of methods:

/// <summary>
///     Manages the simplified key/value store.
/// </summary>
public interface IKeyValueService
{
    /// <summary>
    ///     Gets a value.
    /// </summary>
    /// <remarks>Returns <c>null</c> if no value was found for the key.</remarks>
    string? GetValue(string key);

    /// <summary>
    ///     Returns key/value pairs for all keys with the specified prefix.
    /// </summary>
    /// <param name="keyPrefix"></param>
    /// <returns></returns>
    IReadOnlyDictionary<string, string?>? FindByKeyPrefix(string keyPrefix);

    /// <summary>
    ///     Sets a value.
    /// </summary>
    void SetValue(string key, string value);

    /// <summary>
    ///     Sets a value.
    /// </summary>
    /// <remarks>
    ///     Sets the value to <paramref name="newValue" /> if the value is <paramref name="originValue" />,
    ///     and returns true; otherwise throws an exception. In other words, ensures that the value has not changed
    ///     before setting it.
    /// </remarks>
    void SetValue(string key, string originValue, string newValue);

    /// <summary>
    ///     Tries to set a value.
    /// </summary>
    /// <remarks>
    ///     Sets the value to <paramref name="newValue" /> if the value is <paramref name="originValue" />,
    ///     and returns true; otherwise returns false. In other words, ensures that the value has not changed
    ///     before setting it.
    /// </remarks>
    bool TrySetValue(string key, string originValue, string newValue);
}

Optimizing Your Umbraco Configuration Storage Strategy#

As you can see, whenever you need to store a simple configuration in the database, you should definitely consider using the IKeyValueService to minimize the effort required.

What's next?#

🌐 Explore More: Interested in learning about Umbraco, .NET, and other web development insights? Explore our blog for a wealth of information and expert advice.

✉️Get in Touch: If you have questions or need assistance with your Umbraco projects, don't hesitate to contact us. Our team of experts is always ready to help you navigate any challenges and optimize your digital solutions.

EDITOR'S PICK

↑ Top ↑