Umbraco 8 向RTE添加Macro时all.generated.cs序列化报错如何解决

问题根因 #

这个错误是Umbraco 8 前后端分离架构下的常见问题：

• RTE字段默认启用了Macro渲染逻辑，调用Value()方法获取RTE内容时，Umbraco会自动尝试解析渲染内容里的Macro标签
• Macro渲染依赖当前请求对应的IPublishedContent上下文（也就是报错里的doc参数），在自定义API里直接序列化IPublishedContent模型时，模型属性的延迟求值会触发Macro渲染，这时候上下文传递丢失，就会抛出空参数异常

排查步骤 #

• 进入Umbraco后台「设置」-「数据类型」，找到当前使用的富文本编辑器配置，确认是否勾选了「Render macros in content」选项
• 在API返回序列化之前打个断点，手动调用RTE字段的Value<string>()方法，确认是否是调用该方法时直接抛出异常
• 检查自定义API是否继承了UmbracoApiController，如果是自定义的基础Controller，确认是否正确注入了UmbracoContext，并且请求处理过程中上下文没有被提前释放

解决方案 #

方案一：关闭RTE的自动Macro渲染（推荐，前后端分离场景适用） #

如果前端不需要后端渲染好的Macro内容，打算自己解析Macro标签做前端渲染，直接在RTE数据类型配置里取消勾选「Render macros in content」即可。此时拿到的RTE内容是原始HTML，包含完整的<?UMBRACO_MACRO>标签，可自行在前端解析处理。

方案二：手动渲染Macro再返回 #

如果需要后端直接返回渲染完成的HTML内容，不要直接序列化自动生成的PublishedModel，而是手动处理RTE字段后赋值给自定义DTO再序列化：

// 手动获取原始RTE内容，不触发自动Macro渲染
var rawRteContent = content.GetProperty("你的RTE字段别名").GetValue()?.ToString();
// 手动传入当前上下文和内容对象渲染Macro
var renderedRte = Current.MacroRenderer.RenderRteMacros(rawRteContent, UmbracoContext.Preview.IsPreview, content);
// 把renderedRte赋值给自定义返回DTO，再序列化返回给前端

注意永远不要直接序列化IPublishedContent对象，自定义DTO只返回前端需要的字段，避免触发不必要的属性求值逻辑

方案三：全局替换RTE的值转换器 #

如果需要全局生效，你可以自己实现一个继承自RteMacroRenderingValueConverter的自定义值转换器，重写转换逻辑，在没有上下文的时候直接返回原始内容而不抛出异常，然后通过[PropertyValueType(typeof(string))]和[Weight(int.MaxValue)]标记让你的转换器优先级高于Umbraco默认转换器即可。

内容的提问来源于stack exchange，提问作者Askish