Umbraco CMS 中 Delivery API 内容索引处理器的依赖注入问题解析

在 Umbraco CMS 开发过程中，当开发者尝试为 Delivery API 实现自定义内容索引处理器时，可能会遇到依赖注入相关的问题。本文将深入分析这一技术挑战，并提供多种解决方案。

问题背景

在 Umbraco CMS 13.7.2 版本中，开发者尝试创建一个同时实现 IFilterHandler 和 IContentIndexHandler 接口的类时，遇到了服务注入问题。当尝试在构造函数中注入 IUmbracoContextFactory 和 IPublishedContentQuery 服务时，应用程序启动失败，报错提示无法从单例服务中消费作用域服务。

核心问题分析

这个问题本质上是由 Umbraco 的服务生命周期管理机制引起的：

1. IContentIndexHandler 实现类默认注册为单例(Singleton)服务
2. IPublishedContentQuery 是一个作用域(Scoped)服务
3. 在 .NET 依赖注入系统中，作用域服务不能被单例服务直接消费

解决方案比较

方案一：使用 IPublishedContentQueryAccessor

Umbraco 提供了 IPublishedContentQueryAccessor 服务专门用于解决这类问题：

private readonly IUmbracoContextFactory _umbracoContextFactory;
private readonly IPublishedContentQueryAccessor _publishedContentQueryAccessor;

public RegionFilter(IUmbracoContextFactory umbracoContextFactory, 
                   IPublishedContentQueryAccessor publishedContentQueryAccessor)
{
    _umbracoContextFactory = umbracoContextFactory;
    _publishedContentQueryAccessor = publishedContentQueryAccessor;
}

使用时需要在方法内部检查并获取查询实例：

if (_publishedContentQueryAccessor.TryGetValue(out IPublishedContentQuery? publishedContentQuery))
{
    // 使用 publishedContentQuery 进行操作
}

方案二：手动创建服务作用域

对于更复杂的情况，可以手动创建服务作用域：

using UmbracoContextReference _ = _umbracoContextFactory.EnsureUmbracoContext();
using IServiceScope serviceScope = _serviceProvider.CreateScope();
IPublishedContentQuery query = serviceScope.ServiceProvider.GetRequiredService<IPublishedContentQuery>();

这种方法虽然代码量稍多，但提供了更大的灵活性。

方案三：直接使用 UmbracoContext 内容缓存

如果只是需要访问内容缓存，可以直接通过 UmbracoContext 操作：

using UmbracoContextReference contextReference = _umbracoContextFactory.EnsureUmbracoContext();
IEnumerable<IPublishedContent>? rootContent = contextReference.UmbracoContext.Content?.GetAtRoot(false, culture);

需要注意的是，这种方法只能通过 GetById 单条获取内容，无法批量查询。

性能考量

当需要处理大量内容引用时，直接使用内容缓存可能会面临性能挑战，因为：

1. 只能通过 GetById 单条获取内容
2. 需要循环处理多个引用

在这种情况下，建议：

1. 尽量减少不必要的查询
2. 对结果进行缓存（如果适用）
3. 考虑使用批量处理模式

最佳实践建议

1. 优先使用 IPublishedContentQueryAccessor，它是 Umbraco 专门为解决这类问题设计的
2. 在索引处理器中避免复杂的业务逻辑，保持轻量级
3. 对于大量数据处理，考虑实现缓存机制
4. 在开发过程中充分测试各种边界情况

总结

在 Umbraco CMS 中实现 Delivery API 内容索引处理器时，理解服务生命周期管理至关重要。通过合理选择 IPublishedContentQueryAccessor、手动服务作用域或直接内容缓存等方案，开发者可以构建高效可靠的索引处理逻辑。每种方案都有其适用场景，开发者应根据具体需求选择最合适的实现方式。