Electron.NET 应用生命周期管理：Electron.App API 完整实战指南

桌面应用跨平台【免费下载链接】Electron.NET:electron: Build cross platform desktop apps with ASP.NET Core (Razor Pages, MVC, Blazor).项目地址https://gitcode.com/gh_mirrors/el/Electron.NET点击查看免费下载导读Electron.App是 Electron.NET 中控制桌面应用生命周期与系统集成的核心 API负责应用启动、退出、窗口焦点、单实例锁、协议注册、Jump List、登录项等能力。本文以官方文档 docs/API/App.md 为主体结合 App.cs 与 app.ts 的源码实现系统讲解每一个属性、方法与事件的用法、平台限制与底层调用链帮助你在 ASP.NET Core / Blazor 桌面应用中写出可靠的生命周期代码。OverviewElectron.App 是什么Electron.NET 通过Electron.App静态入口暴露 Electron 主进程app模块的全部能力。它提供应用级事件Ready、BeforeQuit、WillQuit、Quitting、WindowAllClosed等生命周期事件全局状态读写应用名、版本、User Agent、路径等系统集成单实例锁、默认协议处理器、Jump List、登录启动项、badge、Handoff、最近文档等。与 Electron 的app模块一一对应所有 C# 调用都会通过 Socket 桥接到 app.ts 中对应的事件处理器。从源码结构看App类继承ApiBase其方法调用统一由CallMethodN/InvokeAsyncT转发到 Node 端执行见 ApiBase.cs。Properties全局属性CommandLine一个CommandLine对象用于读写 Chromium 使用的命令行参数注意不影响process.argv只控制 Chromium 行为。实现见 CommandLine.csElectron.App.CommandLine.AppendSwitch(disable-gpu); // 追加开关不带 -- 前缀 Electron.App.CommandLine.AppendSwitch(lang, zh-CN); // 带值 Electron.App.CommandLine.AppendArgument(--no-sandbox); // 追加参数自动正确加引号 var has await Electron.App.CommandLine.HasSwitchAsync(lang); // 是否存在 var val await Electron.App.CommandLine.GetSwitchValueAsync(lang); // 取值不存在返回空串建议--switchvalue形式的参数优先用AppendSwitch而非AppendArgument。集成测试 AppTests.cs 验证了 Append → HasSwitch → GetSwitchValue 的完整回环。IsReady布尔属性表示应用宿主是否已完成启动。源码中IsReady的 setter 在置为true时会立即触发所有已注册的Ready处理器App.cs因此即使在Ready之后才订阅事件也能立即收到回调if (Electron.App.IsReady) { /* 已经 ready直接执行 */ }Name/NameAsync当前应用名即 package.json 中name字段。通常 npm 规范下 name 是小写短名若要展示完整名称应在 package.json 中同时提供productName字段Electron 会优先使用。Name的 getter 已标记[Obsolete]同步读取底层会调用NameAsync.Result建议始终使用NameAsyncsetter 通过appSetName事件直接写回App.csNode 端见 app.ts。var name await Electron.App.NameAsync; // 读取 Electron.App.Name My Custom App Name; // 写入UserAgentFallback/UserAgentFallbackAsync全局回退的 User Agent 字符串当 webContents 或 session 级别都没有设置 UA 时使用。为保证覆盖生效应在应用初始化尽可能早的位置设置。Electron.App.UserAgentFallback MyApp/1.0 (Windows NT 10.0; Win64; x64); var ua await Electron.App.UserAgentFallbackAsync; // 回读集成测试 AppTests.cs 做了写入、回读、恢复的完整 roundtrip 验证。Methods方法与平台矩阵生命周期控制Quit / Exit / Relaunch / Focus / Hide / Show方法行为平台Quit()先发BeforeQuit逐个关闭窗口保证 beforeunload/unload 执行成功后发WillQuit并默认退出窗口可在 beforeunload 中返回 false 取消退出全平台Exit(int exitCode 0)立即关闭所有窗口并退出不触发BeforeQuit/WillQuit全平台Relaunch()/Relaunch(RelaunchOptions)当前实例退出后重启不会立即退出需自行调用Quit/Exit多次调用会启动多个新实例全平台Focus()/Focus(FocusOptions)Linux 聚焦第一个可见窗口macOS 激活应用Windows 聚焦第一个窗口全平台Hide()/Show()隐藏/显示所有窗口不最小化、不自动聚焦macOSRelaunchOptions见 RelaunchOptions.cs支持Args重启时替换命令行参数与ExecPath替换为其他可执行文件。FocusOptions.StealmacOS可使应用在别应用活跃时强行成为活跃应用应尽量少用见 FocusOptions.cs。// 重启并带新参数 Electron.App.Relaunch(new RelaunchOptions { Args new[] { --fresh } }); Electron.App.Quit();Node 端实现见 app.tsappQuit/appExit/appRelaunch/appFocus/appHide/appShow。信息查询路径、版本、指标var appPath await Electron.App.GetAppPathAsync(); // 当前应用目录 var version await Electron.App.GetVersionAsync(); // package.json 版本找不到则返回 bundle/exe 版本 var locale await Electron.App.GetLocaleAsync(); // 当前语言环境 var metrics await Electron.App.GetAppMetricsAsync(); // 所有关联进程的内存与 CPU 统计 var gpu await Electron.App.GetGpuFeatureStatusAsync(); // chrome://gpu/ 的 Graphics Feature StatusGetLocaleAsync打包分发时必须一并携带 locales 文件夹Windows 上必须在Ready事件之后调用。GetAppMetricsAsync返回ProcessMetric[]每项包含PId、TypeBrowser/Tab/Utility/GPU 等、Cpu、CreationTime、Memory等字段见 ProcessMetric.cs。GetGpuFeatureStatusAsync仅在gpu-info-update事件发出后才可用。集成测试验证了路径存在性、版本/语言非空、metrics 非空且带 CPU 信息AppTests.cs。特殊目录GetPathAsync / SetPath / SetAppLogsPathGetPathAsync(PathName)返回特殊目录PathName枚举与 Electron 文档对齐Electron API 39.2包括Home、AppData、UserData、SessionData、Temp、Exe、Module、Desktop、Documents、Downloads、Music、Pictures、Videos、RecentWindows、Logs、CrashDumps、AssetsWindows/Linux等见 PathName.cs。var userData await Electron.App.GetPathAsync(PathName.UserData); var temp await Electron.App.GetPathAsync(PathName.Temp);SetAppLogsPath(path)设置/创建日志目录无参时 macOS 为~/Library/Logs/YourAppNameLinux/Windows 为 userData 目录内。若直接调用GetPathAsync(PathName.Logs)而从未调用过SetAppLogsPath会先按无参默认创建日志目录。SetPath(PathName, string)覆盖特殊目录路径目录不存在会抛错需先用fs.mkdirSync之类创建。只能覆盖GetPathAsync定义过的名字默认 cookies/cache 存放在UserData下若需迁移存储位置必须在Ready事件发出之前覆盖UserData。Node 端处理见 app.ts。最近文档AddRecentDocument / ClearRecentDocuments将路径加入 OS 管理的“最近文档”列表Windows 可从任务栏查看macOS 可从 Dock 菜单查看ClearRecentDocuments()清空列表。仅 macOS/Windows。Electron.App.AddRecentDocument(C:\docs\report.pdf); Electron.App.ClearRecentDocuments();默认协议处理器注册与查询让应用成为myapp://一类 URI Scheme 的默认处理器整条链接含协议名会作为参数传入应用。// 注册 var success await Electron.App.SetAsDefaultProtocolClientAsync(myapp); // 校验 var isDefault await Electron.App.IsDefaultProtocolClientAsync(myapp); // 注销 var removed await Electron.App.RemoveAsDefaultProtocolClientAsync(myapp);三个方法均有(string protocol)、(string protocol, string path, ...)、(string protocol, string path, string[] args, ...)重载path默认process.execPathargs默认空数组。底层分别使用 Windows Registry 与 macOSLSSetDefaultHandlerForURLScheme/LSCopyDefaultHandlerForURLSchemeApp.csNode 端 app.ts。注意事项macOS 只能在 info.plist 中声明的协议才能注册运行时不可改需在构建期Electron Forge / Packager或手工编辑 info.plist 完成Windows Storeappx 打包下该 API 恒返回 true但注册表键不可被其他应用读取必须在 manifest 中声明协议macOS 上可用~/Library/Preferences/com.apple.LaunchServices.plist人工校验注册结果。单实例锁RequestSingleInstanceLockAsync防止应用被多次启动返回true表示本进程是主实例、应继续加载返回false表示参数已转交其他实例、应立即退出。var gotLock await Electron.App.RequestSingleInstanceLockAsync( (args, workingDirectory) { // 第二个实例的 args 与工作目录到达时回调 Console.WriteLine($Second instance args: {string.Join(,, args)}); }); if (!gotLock) { Electron.App.Exit(); // 非主实例立即退出 }回调签名Actionstring[], string第一参数为第二实例命令行参数数组第二参数为其工作目录。macOS 上 Finder 双击默认单实例会触发 open-file/open-url 事件但命令行启动绕过系统机制仍需此方法兜底。配套HasSingleInstanceLockAsync()查询当前是否持有锁ReleaseSingleInstanceLock()释放锁以允许多实例并存。底层实现Node 端在收到appRequestSingleInstanceLock后调用app.requestSingleInstanceLock()并监听second-instance事件转发回 C#app.tsC# 端在 App.cs 中反序列化参数并回调。Jump ListWindowsSetUserTasksAsync / SetJumpList / GetJumpListSettingsAsyncJump List 是 Windows 任务栏右键菜单。SetUserTasksAsync(UserTask[])向 tasks 分类添加任务var ok await Electron.App.SetUserTasksAsync(new[] { new UserTask { Program myapp.exe, Arguments --new-document, Title New Document, Description Create a new document, IconPath C:\app\icon.ico, IconIndex 0, WorkingDirectory C:\app } });UserTask全部字段见 UserTask.cs。如需更深度定制用SetJumpList(JumpListCategory[])Electron.App.SetJumpList(new[] { new JumpListCategory { Type JumpListCategoryType.Tasks, Items new[] { /* JumpListItem[] */ } }, new JumpListCategory { Name Recent, Type JumpListCategoryType.Recent } });规则JumpListCategory见 JumpListCategory.cs传入null会恢复 Windows 标准 Jump ListType与Name都未设置 ⇒ 视为tasks只设置Name⇒ 视为custom用户可从自定义分类移除条目Windows 在下一次成功调用SetJumpList前不允许重新加入否则整个自定义分类会被剔除已移除条目列表用GetJumpListSettingsAsync()获取。登录启动项SetLoginItemSettings / GetLoginItemSettingsAsyncElectron.App.SetLoginItemSettings(new LoginSettings { OpenAtLogin true, OpenAsHidden false, // macOS Path C:\Program Files\MyApp\Update.exe, // Windows配合 Squirrel 自动更新 Args new[] { --processStart, MyApp.exe } // Windows }); var settings await Electron.App.GetLoginItemSettingsAsync(); var openAtLogin settings.OpenAtLogin;LoginSettings完整字段macOS/Windows 平台标注见 LoginSettings.csOpenAtLogin默认 false、OpenAsHiddenmacOS、Path/Args/Enabled/NameWindows默认Enabledtrue、Type/ServiceNamemacOS 13。关键提示若SetLoginItemSettings提供了 path 与 args则GetLoginItemSettingsAsync必须传入相同参数LoginItemSettings.OpenAtLogin才会被正确计算。macOS Handoff用户活动// 创建 NSUserActivity可跨设备 Handoff Electron.App.SetUserActivity(com.myapp.edit, new { documentId 123, revision 2 }, https://myapp.com/doc/123); var type await Electron.App.GetCurrentActivityTypeAsync(); // 当前活动类型 Electron.App.ResignCurrentActivity(); // 标记为 inactive 但不作废 Electron.App.InvalidateCurrentActivity(); // 作废当前活动SetUserActivity(type, userInfo, webpageUrl)的三参重载中webpageUrl用于目标设备无合适应用时在浏览器打开必须 http/https源码见 App.cs。仅 macOS。BadgemacOS / Linux UnitySetBadgeCountAsync / GetBadgeCountAsyncawait Electron.App.SetBadgeCountAsync(5); // 设置角标0 隐藏 var count await Electron.App.GetBadgeCountAsync();macOS 显示在 Dock 图标上Linux 仅 Unity launcher 支持且需存在.desktop文件。集成测试对 badge 设置/复位做了平台适配断言AppTests.cs。其他常用方法方法说明平台SetAppUserModelId(string)修改 Windows Application User Model IDWindowsSetAccessibilitySupportEnabled(bool)手动开启 Chromium 无障碍支持默认关闭须在Ready后调用渲染无障碍树会显著影响性能macOS/WindowsIsAccessibilitySupportEnabledAsync()是否已启用检测到屏幕阅读器等辅助技术时返回 truemacOS/WindowsImportCertificateAsync(ImportCertificateOptions)将 pkcs12 证书导入平台证书库返回 0 表示成功其余值对应 chromium net_error_listLinuxIsUnityRunningAsync()当前桌面环境是否为 Unity launcherLinuxShowAboutPanel()/SetAboutPanelOptions(AboutPanelOptions)显示/配置“关于”面板全平台/详见实体SetUserAgentFallback见上文属性全平台AboutPanelOptions见 AboutPanelOptions.cs支持ApplicationName、ApplicationVersion、Copyright、VersionmacOS、CreditsmacOS/Windows、Authors/Website/IconPathLinuxIconPath 在 Windows 用 48x48 PNG 效果最佳。Events生命周期事件App类基于 Socket 桥接注册/注销事件Node 端统一通过register-app-*系列消息注册见 app.ts。主要事件事件触发时机平台备注Ready应用完成基础启动在IsReady之后订阅会立即回调WindowAllClosed所有窗口关闭不订阅则默认退出应用订阅后由你决定是否退出CmdQ 或调用Quit时走 WillQuit 路径不触发本事件BeforeQuit开始关闭窗口前可args.PreventDefault true取消退出AutoUpdater.QuitAndInstall 触发时在所有窗口 close 之后发出Windows 系统关机关机/注销不触发WillQuit所有窗口已关闭、即将退出与 WindowAllClosed 的区别见文档说明Windows 系统关机/注销不触发Quitting应用正在退出Windows 系统关机/注销不触发BrowserWindowBlur/BrowserWindowFocus窗口失焦/聚焦全平台BrowserWindowCreated/WebContentsCreated新 BrowserWindow / WebContents 创建全平台AccessibilitySupportChanged无障碍支持状态变化bool 参数macOS/WindowsOpenFile(string)macOS 用户要打开文件已运行的应用由 OS 复用打开Dock 拖文件且未运行时也会触发Windows 需用App.CommandLine解析参数获取文件路径OpenUrl(string)macOS 用户要打开 URL需在 Info.plist 的CFBundleURLTypes声明 scheme并将NSPrincipalClass设为AtomApplicationElectron.App.Ready () Console.WriteLine(App is ready!); Electron.App.WindowAllClosed () { if (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX)) { Electron.App.Quit(); } };BeforeQuit取消退出演示QuitEventArgs.PreventDefaultElectron.App.BeforeQuit async (args) { var result await Electron.Dialog.ShowMessageBoxAsync(Do you want to quit?); if (result.Response 1) // Cancel { args.PreventDefault true; } };Quit 流程的源码级细节C# 侧BeforeQuit处理器运行后若没有设置PreventDefault会按WillQuit→Quitting→Exit()的顺序推进App.csWindowAllClosed事件在 C# 侧还会额外检查Electron.WindowManager.IsQuitOnWindowAllClosed与 macOS 平台App.cs。监听未映射事件On / OnceApp提供通用的On(eventName, action)/Once(eventName, action)用于订阅 C# 侧尚未显式封装、但 Electronapp模块存在的事件Electron.App.On(certificate-error, (e) { /* ... */ });Node 端通过register-app-on-event/register-app-once-event透传app.ts参数多于一个时取第二个参数透传给 C#。实战组合完整的生命周期编排// ① 早于 Ready覆盖 UserData 存储位置若需要 Electron.App.SetPath(PathName.UserData, /data/myapp); // ② 尽早设置全局 UA Electron.App.UserAgentFallback MyApp/2.0; // ③ Ready 后启动 UI Electron.App.Ready async () { var mainWindow await Electron.WindowManager.CreateWindowAsync(); await mainWindow.WebContents.LoadURLAsync(http://localhost:8001); }; // ④ 全部窗口关闭macOS 常驻其他平台退出 Electron.App.WindowAllClosed () { if (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX)) { Electron.App.Quit(); } }; // ⑤ 退出前确认可选 Electron.App.BeforeQuit (args) Task.CompletedTask;相关 API 与延伸阅读Electron.WindowManager窗口创建与管理与BrowserWindowCreated、WindowAllClosed联动Electron.DialogBeforeQuit中做退出确认对话框Electron.Menu应用菜单与SetLoginItemSettings配合的桌面集成Startup Methods不同的应用启动模式决定Ready触发的进程上下文源码与测试App.cs、app.ts、AppTests.cs小结Electron.App是 Electron.NET 桌面应用的“总开关”Ready决定 UI 启动时机WindowAllClosed/BeforeQuit/WillQuit决定退出策略单实例锁与协议注册决定应用如何被 OS 唤起Jump List、登录项、badge 决定应用与系统的集成深度。所有异步方法都支持CancellationToken取消且绝大多数查询类方法带 1 秒调用超时保护见 ApiBase.cs编写生命周期代码时应始终使用async版本并合理处理返回值避免同步阻塞桥接通道。赞分享桌面应用跨平台【免费下载链接】Electron.NET:electron: Build cross platform desktop apps with ASP.NET Core (Razor Pages, MVC, Blazor).项目地址https://gitcode.com/gh_mirrors/el/Electron.NET点击查看免费下载相关推荐ngx-loading-bar版本迁移指南从Angular 13到16的平滑升级ngx loading bar版本迁移指南从Angular 13到16的平滑升级 ngx loading bar是一款为Angular应用提供自动页面加载进度最完整的Goroutine生命周期管理run.Group实战指南最完整的Goroutine生命周期管理run.Group实战指南 你是否还在为Go项目中goroutine的混乱管理而头疼多个并发任务如何优雅启停异常退出Prosopite最佳实践避免误报的允许列表和忽略查询配置Prosopite最佳实践避免误报的允许列表和忽略查询配置 Prosopite是一款针对Rails应用的N1查询自动检测工具能够帮助开发者精准识别并优化低开发工具上一篇双语翻译配置思维如何用kiss-translator构建个性化多语言工作流下一篇三步搞定跨网络远程桌面控制UltraVNC终极免费方案指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考