Missing Documentation for NuCache JSON Serialization Option in Umbraco v13

[devlopaag]

What type of issue is it?
Missing documentation

What article/section is this about?
(No specific link, as this option is not documented anywhere. It should be part of the NuCache settings documentation.)

Describe the issue
While upgrading from Umbraco v8 to v13, I encountered major difficulties retrieving JSON content from cmsContentNu as in previous versions. After hours of troubleshooting, I discovered the following undocumented option:

builder.Services.Configure<NuCacheSettings>(options =>
{
    options.NuCacheSerializerType = NuCacheSerializerType.JSON;
});

This configuration option resolves issues where JSON serialization of NuCache content is required. However, it is not documented anywhere. I spent over 8 hours debugging something that could have been solved quickly if this option had been properly documented.

Expected Outcome
This configuration option should be:

Documented in the NuCache settings section.
Clearly explained regarding its purpose and behavior.
If deprecated or not recommended, marked accordingly with an explanation.

Why is this important?
Lack of documentation caused wasted development hours and unnecessary frustration. Proper documentation for this setting will save time for developers, especially those migrating from older versions (v8 to v13).

Steps to Reproduce

1. Upgrade an Umbraco project from v8 to v13.
2. Attempt to retrieve JSON content from cmsContentNu.
3. Notice that the content format has mysteriously changed.
4. Spend ages trying to figure out that the "current format" is MessagePack – oh, and for some reason, it has double compression!?!?
5. After nearly losing your sanity, stumble upon the undocumented NuCacheSerializerType.JSON setting, which solves everything.

[sofietoft]

Hi @devlopaag !
Thanks for the thorough and very detailed report 💪
It sure sounds like you've found a pretty significant gab in our documentation, and I'll make sure we get this remedied as soon as possible.

To make sure I understand exactly what is needed, here's my two cents on what should happen:

• We need to article this article: https://docs.umbraco.com/umbraco-cms/13.latest/reference/configuration/nucachesettings
• The article needs to be updated with a section about the NuCacheSerializerType setting.
• The section should include information about what this settings does, when it should be used and for what.

Does that sound correct to you?

[devlopaag]

Hi @sofietoft 👋,

thank you for the quick response and for acknowledging the issue! 💪

Yes, you’ve summarized it perfectly. The article absolutely needs a section about the NuCacheSerializerType setting, covering:

• What it does (e.g., allowing JSON serialization instead of the current default).
• When and why it should be used, especially for developers migrating from v8 who might rely on JSON formats.
• Clarification on the current default format – namely MessagePack with double compression – because this wasn’t exactly intuitive to discover.

Additionally, it’s very important to explicitly mention the cmsContentNu table in the documentation. Developers searching for information about the data and dataRaw columns in this table will naturally expect related documentation to point them towards this setting. Without this connection, it’s easy to get stuck without realizing that NuCacheSerializerType is the solution.

Having this information in the docs will save developers from hours of unnecessary digging (like I experienced). Looking forward to seeing the update soon!

Best regards

[sofietoft]

Excellent. Thanks for confirming @devlopaag !

I'll make sure we look into this as soon as possible.