[Breaking change]: Settings will change from Arrays to ISet<T>s in Umbraco 16

[bergmania]

Description

In Umbraco 16, we are refactor settings from using Arrays to Sets to ensure that values are unique and can be easily modified from the code. This change will improve how collections of values are managed, providing better flexibility and ensuring that duplicate entries are not allowed.

Version

Umbraco 16

Previous behavior

Previously, enumerable settings in Umbraco were stored as Arrays. Arrays allow duplicate values and require more manual handling when ensuring the uniqueness of items and when manipulating the values in code.

New behavior

In Umbraco 16, enumerable settings will be stored as sets when it make sense. Sets automatically enforce uniqueness, preventing duplicate values from being added. Additionally, sets provide better mutability and allow more efficient operations when modifying or updating collections in code.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

The change to sets was made to provide a more robust and efficient way to handle collections of values in settings. By enforcing unique values, sets eliminate potential issues with duplicates, and their mutability ensures that developers can more easily modify collections from code.

Consider removing TIFF and adding PBM and TGA image file types on the ContentImagingSettings configuration. Even when using the spread element .. to make adding items to the array easier, removing an existing item requires filtering the existing array:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Configuration.Models;

public class ImageFileTypesComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ContentImagingSettings>(options =>
        {
            options.ImageFileTypes =
            [
                // Remove TIFF
                ..options.ImageFileTypes.Where(x => x == "tiff"),
                // Add PBM and TGA
                "pbm",
                "tga"
            ];
        });
}

With this change applied, the ImageFileTypes is now an ISet<string>, which can easily be mutated:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Configuration.Models;

public class ImageFileTypesComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ContentImagingSettings>(options =>
        {
            // Remove TIFF
            options.ImageFileTypes.Remove("tiff");

            // Add PBM and TGA
            options.ImageFileTypes.Add("pbm");
            options.ImageFileTypes.Add("tga");
        });
}

Recommended action

If your existing code manipulates settings stored in arrays directly in code, using the IOptions pattern, you will need to update those parts of your codebase to work with the new ISet<T> instead.

Affected APIs

• BasicAuthSettings.AllowedIPs
• ContentImagingSettings.ImageFileTypes
• ContentImagingSettings.AutoFillImageProperties
• ContentSettings.Error404Collection
• ContentSettings.AllowedUploadedFileExtensions
• ContentSettings.DisallowedUploadedFileExtensions
• ContentSettings.AllowedMediaHosts
• ApiSettings.DisallowedContentTypeAliases
• ApiSettings.LogoutRedirectUrls
• HelpPageSettings.HelpPageUrlAllowList
• InstallDefaultDataSettings.Values
• RequestHandlerSettings.UserDefinedCharCollection
• TypeFinderSettings.AdditionalEntryAssemblies
• TypeFinderSettings.AdditionalAssemblyExclusionEntries
• InstallDefaultDataSettings.Values