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
[X] Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
[X] 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.
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
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:With this change applied, the
ImageFileTypes
is now anISet<string>
, which can easily be mutated: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 newISet<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