GeneralUpdate.Avalonia.Android
命名空间: GeneralUpdate.Avalonia.Android | 主要入口: GeneralUpdateBootstrap.CreateDefault() | NuGet 包: GeneralUpdate.Avalonia.Android
1. 组件简介
1.1 组件概述
GeneralUpdate.Avalonia.Android 是面向 Avalonia 12+ 应用的 Android 平台自动更新核心库(无 UI,net10.0-android),专为 Android APK 的更新场景设计。它提供版本查询与对比、可断点续传的 APK 下载、SHA256 完整性校验、Android Package Installer 拉起,以及安装结果闭环核对的全流程编排能力。
Android 平台的更新与桌面应用不同:APK 安装必须通过 Android 系统安装器完成,下载过程可能被用户中断或切换网络,安装前需要检查"安装未知应用"权限,而且安装期间当前进程会被系统结束。该组件封装了这些平台差异,并额外解决了"安装器已拉起 ≠ 安装成功"的确认问题。
核心能力:
| 能力 | 说明 |
|---|---|
| 服务端版本查询 | 组件按 UpdateServerOptions 内部请求服务端,调用方只需提供设备上的当前版本 |
| 版本对比 | 内置 SystemVersionComparer,通过 IVersionComparer 接口支持自定义版本策略 |
| 一体化流程 | PrepareUpdateAsync 在同一个操作锁内完成查询 → 预检查 → 下载 → 校验 |
| 断点续传下载 | HttpResumableApkDownloader 基于 HTTP Range + Sidecar 元数据,中断后可续传 |
| SHA256 完整性校验 | 下载完成后自动计算 SHA256,与服务端声明的哈希比对,并校验文件大小 |
| APK 安装编排 | 通过 AndroidApkInstaller 调用系统 Package Installer,自动处理 FileProvider URI |
| 安装结果闭环 | CheckInstallationAsync / ResetInstallationAsync 依据持久化记录核对本次更新是否真正生效 |
| 更新前回调 | AddListenerUpdatePrecheck 在下载前把更新信息交给业务层,可跳过本次更新 |
| HTTP 传输配置 | HttpDownloadOptions 支持 SSL/TLS 证书策略、代理、超时、重试和认证 |
| 多协议认证 | HMAC-SHA256、Bearer Token、API Key、HTTP Basic,可全局或单包粒度配置 |
| 事件通知 | 验证、下载进度、完成、安装确认、失败五类事件 |
| 状态快照 | GetSnapshot() 随时获取当前更新状态、失败原因和消息 |
| UI 线程调度 | IUpdateEventDispatcher 支持把事件调度到 UI 线程(如 Avalonia 的 Dispatcher.UIThread) |
| 操作串行化 | 内部 SemaphoreSlim(1,1) 操作门,并发调用自动排队,线程安全 |
| 可替换抽象 | 版本比较、下载、哈希、安装、存储、包源、事件调度、日志全部可替换 |
解决的业务痛点:
- Avalonia 应用发布 Android 版本后,需要可靠的内置更新能力,但 Android APK 安装必须经由系统安装器
- 调用方不应重复实现"查询版本接口 + 挑选最新包 + 比较版本"的样板代码
- 下载大 APK 时可能被中断或切换网络,需要断点续传降低流量消耗
- 需要校验下载包的完整性,防止传输损坏或被篡改
- 安装器返回
Success并不代表用户完成了安装,需要跨进程的安装结果确认机制 - 需要灵活的认证方案对接不同服务端的鉴权要求
Android 更新 ≠ 桌面文件替换
Android 平台不能像桌面端那样直接替换文件。APK 必须通过 Android Package Installer 安装,系统会处理签名验证、权限授予和应用替换。本组件封装了这些平台差异,但 APK 签名、包名一致、versionCode 递增等仍需要你在构建流水线中保证。组件也不提供静默安装、自动重启或回滚。
业务使用场景:
- Avalonia 跨平台应用的 Android APK 自动更新
- 企业内部 Android 应用的分阶段、可确认式更新
- 需要通过 CDN / OSS 分发 APK 包的场景
- 需要对接 GeneralUpdate 示例服务端
/Upgrade/Verification协议或静态 JSON 端点的场景
1.2 环境与依赖
| 项目 | 说明 |
|---|---|
| NuGet 包 | GeneralUpdate.Avalonia.Android(仓库当前版本 v0.0.1-beta.10) |
| 目标框架 | net10.0-android(SupportedOSPlatformVersion = 26.0) |
| .NET SDK | 10.0+ |
| Avalonia | 12+ |
| 依赖包 | Xamarin.AndroidX.Core(FileProvider 支持) |
| 兼容性 | Android 8.0 (API 26) 及以上版本 |