.NET MAUI 依赖注入完全指南MauiProgram 服务注册、生命周期选择与 Shell 自动解析【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills本指南以 dotnet-maui 技能库中的maui-dependency-injection技能SKILL.md 与 dependency-injection-api.md为核心骨架编写。它面向正在为 .NET MAUI 应用搭建依赖注入DI体系的开发者覆盖服务在MauiProgram.CreateMauiApp()中的注册方式、AddSingleton/AddTransient/AddScoped生命周期取舍、构造函数注入、ViewModel 与 Page 的绑定接线、Shell 路由导航自动解析以及平台条件注册与可测试性设计。读完本文你将能独立完成一个 MAUI 应用的 DI 全链路配置并规避 ShellContentTemplate绕过容器、AddScoped失效等高频陷阱。一、核心认知MAUI 与 ASP.NET Core 共用同一 DI 容器.NET MAUI 使用的正是 ASP.NET Core 背后的Microsoft.Extensions.DependencyInjection容器而不是一套自造的机制。所有服务注册都发生在MauiProgram.CreateMauiApp()中的builder.Services上容器在启动时构建一次此后不可变immutable。这意味着你在 ASP.NET Core 中积累的注册语法、扩展方法如AddSingleton、AddTransient与IServiceProvider解析习惯在 MAUI 中几乎可以原样迁移。在 plugins/dotnet-maui 插件中本技能与maui-data-binding、maui-shell-navigation等技能形成互补分工本文只负责服务如何注册、如何被解析XAML 数据绑定语法请交由maui-data-binding技能Shell 路由与查询参数的配置请参阅maui-shell-navigation技能。二、服务注册MauiProgram.cs 中的标准写法注册的入口只有一个——CreateMauiApp()内的builder.Services。API 参考文档 dependency-injection-api.md 给出了最基础的三段式注册服务、ViewModel、页面。public static MauiApp CreateMauiApp() { var builder MauiApp.CreateBuilder(); builder.UseMauiAppApp(); // Services builder.Services.AddSingletonIDataService, DataService(); builder.Services.AddTransientIApiClient, ApiClient(); // ViewModels builder.Services.AddTransientMainViewModel(); builder.Services.AddTransientDetailViewModel(); // Pages builder.Services.AddTransientMainPage(); builder.Services.AddTransientDetailPage(); return builder.Build(); }SKILL.md 在此基础上给出了更贴近真实项目的分组式注册并引入了 HTTP 客户端的推荐做法public static MauiApp CreateMauiApp() { var builder MauiApp.CreateBuilder(); builder.UseMauiAppApp(); // Services —— 共享状态用 Singleton builder.Services.AddSingletonIDataService, DataService(); builder.Services.AddSingletonISettingsService, SettingsService(); // HTTP —— 优先使用类型化客户端IHttpClientFactory // 需要 NuGet 包Microsoft.Extensions.Http builder.Services.AddHttpClientIApiClient, ApiClient(); // ViewModels —— Transient 保证每次导航都有新实例 builder.Services.AddTransientMainViewModel(); builder.Services.AddTransientDetailViewModel(); // Pages —— Transient 保证每次构造都触发构造函数注入 builder.Services.AddTransientMainPage(); builder.Services.AddTransientDetailPage(); return builder.Build(); }两个要点值得注意类型化 HttpClientAddHttpClientIApiClient, ApiClient()走的是IHttpClientFactory由Microsoft.Extensions.Http包提供。它自动管理HttpClientHandler的生命周期避免传统HttpClient手动 new 带来的 socket 耗尽问题这也是共享型服务Singleton的典型代表。分组注释SKILL.md 的 Workflow 明确要求按Services、HTTP、ViewModels、Pages分组注册方便后续审计与维护。三、生命周期选择Singleton / Transient / Scoped生命周期是整个 DI 配置中最容易出错、也最影响运行行为的部分。两份文档都提供了对照表合并整理如下生命周期使用场景典型类型AddSingletonT()共享状态、创建成本高、应用级配置HttpClient工厂、设置服务、数据库连接AddTransientT()轻量、无状态、或每次使用都需新实例页面、ViewModel、按调用创建的 API 封装AddScopedT()窗口级生命周期或手动创建的IServiceScope作用域内工作单元MAUI 中很少用核心规则Page 和 ViewModel 默认注册为 Transient共享服务注册为 Singleton。关于AddScopedSKILL.md 给出了 MAUI 与 ASP.NET Core 的关键差异警告⚠️除非手动管理IServiceScope否则避免使用AddScoped。MAUI 没有 ASP.NET Core 那样的内置请求作用域。MAUI 每个窗口Window会创建一个IServiceScope因此 Scoped 服务的生命周期等于该窗口的存活期而从根 provider 解析时它又静默地表现为 Singleton。两者都无法提供每次导航新建的新鲜度。也就是说从 ASP.NET Core 迁移过来的开发者如果习惯性地把DbContext或工作单元注册为AddScoped在 MAUI 中会发现数据跨页面持久化——这正是评测用例tests/dotnet-maui/maui-dependency-injection/eval.yaml中专门设置的一个诊断场景。正确的替代方案是需要每次导航新建时用AddTransient需要全局共享时用AddSingleton只有确实需要显式控制作用域时才这样做// 确实需要工作单元语义时显式创建作用域 using var scope scopeFactory.CreateScope(); var db scope.ServiceProvider.GetRequiredServiceMyDbContext();SKILL.md 还强调在回答该用哪个生命周期这类问题时应给出带取舍的完整菜单AddTransient、显式IServiceScopeFactory.CreateScope()、工厂模式AddDbContextFactory并说明各自适用场景而不是一句话开药方。四、构造函数注入容器自动解析依赖构造函数注入是首选的依赖获取方式。当类型本身由容器解析时容器会自动实例化其构造函数中的全部依赖public class MainViewModel { private readonly IDataService _dataService; private readonly IApiClient _apiClient; public MainViewModel(IDataService dataService, IApiClient apiClient) { _dataService dataService; _apiClient apiClient; } }SKILL.md 中的版本进一步展示了 ViewModel 如何使用注入的服务完成业务动作public class MainViewModel { private readonly IDataService _dataService; public MainViewModel(IDataService dataService) { _dataService dataService; } public async Task LoadAsync() Items await _dataService.GetItemsAsync(); }4.1 ViewModel → Page 接线模式页面的典型装配方式是同时注册 ViewModel 与 Page把 ViewModel 注入 Page 构造函数并赋给BindingContextpublic partial class MainPage : ContentPage { public MainPage(MainViewModel viewModel) { InitializeComponent(); BindingContext viewModel; } }这样 XAML 中的数据绑定表达式如{Binding Items}就能直接命中 ViewModel 的属性而MainPage自身的创建由容器负责无需手动 new。五、Shell 导航自动解析DI 与路由的协同当 Page 既注册进 DI 容器、又注册为 Shell 路由时Shell 会在导航时自动解析它及其完整依赖图// MauiProgram.cs builder.Services.AddTransientDetailPage(); builder.Services.AddTransientDetailViewModel(); // AppShell.xaml.cs Routing.RegisterRoute(nameof(DetailPage), typeof(DetailPage)); // 导航 —— DI 负责解析 DetailPage 及其 DetailViewModel await Shell.Current.GoToAsync(nameof(DetailPage));配套的完整工作流来自 SKILL.md 的 Workflow 章节为识别所有需要参与 DI 的服务、ViewModel 与 Page为每个类型选择正确生命周期——共享服务用 SingletonPage 与 ViewModel 用 Transient在CreateMauiApp()的builder.Services上分组注册所有类型在AppShell.xaml.cs中把 Page 注册为 Shell 路由让 Shell 导航自动解析完整依赖图通过构造函数注入把每个 Page 与其 ViewModel 接线并将 ViewModel 赋为BindingContext用#if指令添加平台特定注册确保每个目标平台都有覆盖或兜底运行应用验证解析正常确认运行时没有null依赖或缺失注册异常。5.1 向 DI 解析的 ViewModel 传参IQueryAttributable导航参数与 DI 注入的依赖是两条独立通道。DI 提供 ViewModel 的依赖导航参数则通过查询字符串单独送达。不要试图把导航参数塞进构造函数正确做法是让 ViewModel 实现IQueryAttributablepublic class DetailViewModel : ObservableObject, IQueryAttributable { readonly IDataService _data; // ← 由 DI 注入 public DetailViewModel(IDataService data) _data data; public void ApplyQueryAttributes(IDictionarystring, object query) { // ← 由导航提供 if (query.TryGetValue(id, out var id)) LoadAsync(id.ToString()!); } } // 带参数导航 —— 页面与其 ViewModel 依然来自 DI await Shell.Current.GoToAsync(${nameof(DetailPage)}?id{product.Id});Shell 会把查询属性应用到 Page以及它的BindingContext上因此 ViewModel 无需任何页面侧接线即可收到参数。六、显式解析构造函数不可用时的最后手段构造函数注入应作为默认方案只有在注入确实不可用如自定义 Handler、平台回调时才使用显式解析。API 参考文档给出的方式是从任意拥有 Handler 的 Element 获取服务// 从任意具有 Handler 的 Element 中 var service this.Handler.MauiContext.Services.GetServiceIDataService();当需要动态解析服务时可以注入IServiceProviderpublic class MyService { private readonly IServiceProvider _serviceProvider; public MyService(IServiceProvider serviceProvider) { _serviceProvider serviceProvider; } public void DoWork() { var api _serviceProvider.GetRequiredServiceIApiClient(); } }SKILL.md 中的简化写法C# 12 主构造函数同样可行public class NavigationService(IServiceProvider serviceProvider) { public T ResolvePageT() where T : Page serviceProvider.GetRequiredServiceT(); }需要强调的是显式解析服务定位器会隐藏依赖关系、增加测试难度SKILL.md 将其明确列为反模式见后文常见陷阱第 4 条应始终作为最后手段。七、平台特定服务注册用 #if 覆盖每个目标平台移动与桌面应用常需要按平台切换实现如通知服务在 Android / iOS / Windows 上各不相同。使用预处理器指令在MauiProgram.cs中条件注册// 在 MauiProgram.cs 中 #if ANDROID builder.Services.AddSingletonINotificationService, AndroidNotificationService(); #elif IOS || MACCATALYST builder.Services.AddSingletonINotificationService, AppleNotificationService(); #elif WINDOWS builder.Services.AddSingletonINotificationService, WindowsNotificationService(); #else builder.Services.AddSingletonINotificationService, NoOpNotificationService(); #endif关键要求要么覆盖所有目标平台要么提供 no-op 兜底实现。缺失某个平台分支意味着该平台运行时GetServiceT()返回null触发解析异常。#else分支如NoOpNotificationService是防御性最佳实践——即使未来新增目标平台也不会因为注册遗漏而崩溃。八、接口优先模式为可测试性设计为服务定义接口使测试中可以替换实现而不触碰生产代码public interface IDataService { TaskListItem GetItemsAsync(); } public class DataService : IDataService { public async TaskListItem GetItemsAsync() { /* ... */ } } // 注册接口 → 实现映射 builder.Services.AddSingletonIDataService, DataService();测试中直接用一个ServiceCollection重建容器并替换实现var services new ServiceCollection(); services.AddSingletonIDataService, FakeDataService();这种接口 容器重建的组合让单元测试完全脱离真实网络与设备依赖。注意 SKILL.md 的提醒不要为了对称性而凭空添加接口只有当用户要求或确实修复真实缺陷时才引入——接口的唯一目的应当是支持替换与测试。九、六大常见陷阱源码级解读SKILL.md 用大量篇幅总结了 MAUI DI 的高频踩坑点其中第 2 条给出了真实的框架内部行为值得逐条精读。9.1 Singleton ViewModel 导致数据陈旧// ❌ ViewModel 在多次导航间保留陈旧状态 builder.Services.AddSingletonDetailViewModel(); // ✅ 每次导航都获得新实例 builder.Services.AddTransientDetailViewModel();Singleton 页面还有一个致命问题被移出视觉树后无法重新加入。因此除根 Tab 页想保持常驻这类确有单一实例需求的场景外页面一律 Transient。9.2 ContentTemplate 页面不经过 DI 创建框架源码行为这是最容易困惑的场景。Page 若在 Shell XAML 中通过以下方式声明ShellContent ContentTemplate{DataTemplate views:DetailPage} /它由Activator.CreateInstance实例化对应 MAUI 的ElementTemplate.cs完全不经过服务提供程序。构造函数注入在此路径上不生效如果页面唯一的构造函数带依赖参数你会得到MissingMethodException——而不是静默的null依赖。而通过Routing.RegisterRouteGoToAsync到达的页面走的是ActivatorUtilities.GetServiceOrCreateInstance对应Routing.cs即使页面类型本身从未注册也会注入已注册的依赖并且在某个必需依赖无法解析时抛出异常。// 同时注册页面与依赖两条路径都能工作 builder.Services.AddTransientDetailPage(); builder.Services.AddTransientDetailViewModel();如果确实需要为 Tab/Flyout 页面启用 DI两种出路给页面一个无参构造函数并自行解析所需服务或者改为按路由导航而不是嵌入ContentTemplate。这一行为在评测配置tests/dotnet-maui/maui-dependency-injection/eval.yaml中被专门验证并作为回归守卫要求模型不得声称依赖会被静默置为 null 且无异常。9.3 XAML 资源解析 vs DI 时序App.xaml中的资源在InitializeComponent()期间解析此时容器尚未完全可用。依赖服务的初始化应推迟到CreateWindow()public partial class App : Application { private readonly IServiceProvider _services; public App(IServiceProvider services) { _services services; InitializeComponent(); } protected override Window CreateWindow(IActivationState? activationState) { // 此时容器已完整构建安全 // 需要先注册builder.Services.AddTransientAppShell() var appShell _services.GetRequiredServiceAppShell(); return new Window(appShell); } }注意App本身也是从容器解析的builder.UseMauiAppApp()因此它可以通过构造函数拿到IServiceProvider。9.4 服务定位器反模式// ❌ 隐藏依赖、难以测试 var svc this.Handler.MauiContext.Services.GetServiceIDataService(); // ✅ 构造函数注入 —— 显式且可测试 public class MyViewModel(IDataService dataService) { }9.5 条件注册遗漏平台忘记#if块中的某个平台该平台运行时GetServiceT()返回null。始终包含#else兜底或覆盖全部目标平台见第七章。9.6 无手动作用域的 AddScopedAddScoped在 MAUI 中要么是窗口生命周期要么是根解析时的 Singleton 行为永远不是每次导航新建。除非显式创建并管理IServiceScope否则应改用AddTransient或AddSingleton。十、技能配套与评测验证本技能在仓库中的完整配套如下主文档plugins/dotnet-maui/skills/maui-dependency-injection/SKILL.md——包含使用时机、规则表、工作流、生命周期对照、完整代码示例与六大陷阱API 参考plugins/dotnet-maui/skills/maui-dependency-injection/references/dependency-injection-api.md——本指南的骨架文档聚焦注册 API、生命周期表、构造函数注入、Shell 自动解析、显式解析与平台注册评测配置tests/dotnet-maui/maui-dependency-injection/eval.yaml——五个评测刺激项分别验证生命周期正确的MauiProgram注册、Shell 导航自动解析接线、平台条件注册含兜底、AddScoped陷阱诊断、ContentTemplate与路由两条路径的差异化行为插件清单plugins/dotnet-maui/plugin.json——dotnet-maui插件版本 0.1.16将./skills/目录下的技能统一暴露给 Agent。该技能的使用边界也定义得很清晰XAML 数据绑定语法请交给maui-data-binding技能Shell 路由注册与查询参数交给maui-shell-navigation技能Mock 框架与测试运行器则使用标准的 xUnit / NUnit / MSTest 与 NSubstitute / Moq——DI 只负责怎么把依赖注入进来不负责怎么替换依赖去测试。十一、最终检查清单把以下清单当作每次配置 MAUI DI 的收尾检查每个需要注入的 Page 和 ViewModel 都已注册在MauiProgram.csPage 与 ViewModel 使用AddTransient共享服务使用AddSingleton尽可能使用构造函数注入服务定位器仅作最后手段需要测试替换的服务已定义接口平台特定#if注册覆盖全部目标平台或包含兜底依赖服务的初始化推迟到CreateWindow()不在 XAML 解析期间执行AddScoped仅用于确实需要窗口级生命周期或配合手动创建的IServiceScope遵循上述规则你可以让 MAUI 应用的依赖关系显式、可测、可维护并让 Shell 导航、平台适配与单元测试三条链路都顺畅运转。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考