Skip to content

Commit 21cbed4

Browse files
JusterZhuclaude
JusterZhu
and
claude
authored
docs: add GeneralUpdate.Avalonia and GeneralUpdate.Maui component docs & cookbooks (#120)
- Add GeneralUpdate.Avalonia.Android and GeneralUpdate.Maui.Android component reference docs (zh-CN + EN) - Add Avalonia Android and MAUI Android quickstart cookbooks - Update GeneralUpdate.Tools doc with Mobile packaging module - Update Component Introduction with Avalonia repository entry - Update Release Log with v10.5.0-beta.4 entries - Update sidebars.js and category.json for new pages Co-authored-by: Claude <noreply@anthropic.com>
1 parent 53efc31 commit 21cbed4

19 files changed

Lines changed: 3652 additions & 10 deletions

‎website/docs/doc/Component Introduction.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ GeneralUpdate is an open-source cross-platform application automatic update comp
9191
| Name | Description | Address |
9292
| --------------------- | -------------------------- | ------------------------------------------------------------ |
9393
| GeneralUpdate | Automatic Updates | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate)<br />[Gitee](https://gitee.com/GeneralLibrary/GeneralUpdate)<br />[GitCode](https://gitcode.com/GeneralLibrary/GeneralUpdate) |
94-
| GeneralUpdate.Maui | Maui Updates (Android) | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate.Maui)<br />[Gitee](https://gitee.com/GeneralLibrary/GeneralUpdate.Maui)<br />[GitCode](https://gitcode.com/GeneralLibrary/GeneralUpdate-Maui) |
94+
| GeneralUpdate.Maui | MAUI Android Auto-Updates | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate.Maui)<br />[Gitee](https://gitee.com/GeneralLibrary/GeneralUpdate.Maui)<br />[GitCode](https://gitcode.com/GeneralLibrary/GeneralUpdate-Maui) |
95+
| GeneralUpdate.Avalonia | Avalonia Android Auto-Updates | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate.Avalonia) |
9596
| GeneralUpdate.Tools | Update Patch Creation Tool | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate.Tools)<br />[Gitee](https://gitee.com/GeneralLibrary/GeneralUpdate.Tools)<br />[GitCode](https://gitcode.com/GeneralLibrary/GeneralUpdate-Tools) |
9697
| GeneralUpdate-Samples | Usage Examples | [GitHub](https://github.com/GeneralLibrary/GeneralUpdate-Samples)<br />[Gitee](https://gitee.com/GeneralLibrary/GeneralUpdate-Samples)<br />[GitCode](https://gitcode.com/GeneralLibrary/GeneralUpdate-Samples) |
9798

‎website/docs/doc/GeneralUpdate.Avalonia.Android.md‎

Lines changed: 653 additions & 0 deletions
Large diffs are not rendered by default.

‎website/docs/doc/GeneralUpdate.Maui.Android.md‎

Lines changed: 738 additions & 0 deletions
Large diffs are not rendered by default.

‎website/docs/doc/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@
33
"position": 2,
44
"link": {
55
"type": "generated-index",
6-
"description": "GeneralUpdate 组件参考文档 — 涵盖 Core、Bowl、Differential、Drivelution 与 Extension 五大非固件组件。"
6+
"description": "GeneralUpdate 组件参考文档 — 涵盖 Core、Bowl、Differential、Drivelution、Extension、Avalonia.Android 与 Maui.Android 七大非固件组件。"
77
}
88
}

‎website/docs/quickstart/Avalonia Android cookbook.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
sidebar_position: 4
3+
title: Avalonia Android 更新入门
4+
---
5+
6+
# GeneralUpdate.Avalonia.Android 快速入门
7+
8+
这篇手册面向需要在 Avalonia 应用中集成 Android APK 自动更新的开发者。目标是用最少的代码跑通"检查更新 → 下载 APK → 校验 SHA256 → 启动安装器"的完整流程。
9+
10+
:::info 前置知识
11+
这篇手册假设你已经有一个 Avalonia 项目并配置好了 Android 目标框架。如果你还没有 Avalonia Android 项目，请先参考 [Avalonia 官方文档](https://docs.avaloniaui.net/) 创建。
12+
:::
13+
14+
## 更新流程
15+
16+
```
17+
① 检查版本 ② 下载 APK ③ 安装
18+
┌──────────┐ ┌──────────┐ ┌──────────────┐
19+
│ Client │──POST──→ │ Server │ │ Android │
20+
│(Avalonia)│←─JSON─── │(更新服务)│ │ Package │
21+
└────┬─────┘ └────┬─────┘ │ Installer │
22+
│ │ └──────┬───────┘
23+
│ 服务器返回包信息 │ │
24+
│ ←────────────────────│ │
25+
│ │ │
26+
│ GET /packages/app-v2.0.0.apk │
27+
│ ────────────────────→│ │
28+
│ APK 文件 (支持 Range)│ │
29+
│ ←────────────────────│ │
30+
│ │ │
31+
│ SHA256 校验通过后 │ │
32+
│ 启动 Package Installer ─────────────────→ │
33+
│ │ │
34+
```
35+
36+
| 角色 | 定义 | 负责什么 |
37+
| --- | --- | --- |
38+
| Client（Avalonia） | 你的 Avalonia Android 应用 | 检查版本 → 下载 APK → 校验 → 启动安装器 |
39+
| Server | 更新服务（如 Samples 中的 Server） | 返回版本信息、提供 APK 下载 |
40+
| Android Package Installer | Android 系统组件 | 安装 APK（验证签名、替换应用） |
41+
42+
## Phase 1：环境准备
43+
44+
### 安装清单
45+
46+
| 项 | 要求 | 验证命令 |
47+
| --- | --- | --- |
48+
| .NET SDK | 10.0+ | `dotnet --version` |
49+
| Android SDK | API 26+ | `dotnet workload list`（应包含 `android`） |
50+
51+
### NuGet 包
52+
53+
```bash
54+
dotnet add package GeneralUpdate.Avalonia.Android
55+
```
56+
57+
## Phase 2：FileProvider 配置
58+
59+
APK 文件需要通过 FileProvider 传递给 Android Package Installer。在 `AndroidManifest.xml` 中添加：
60+
61+
```xml
62+
<application>
63+
<provider
64+
android:name="androidx.core.content.FileProvider"
65+
android:authorities="${applicationId}.fileprovider"
66+
android:exported="false"
67+
android:grantUriPermissions="true">
68+
<meta-data
69+
android:name="android.support.FILE_PROVIDER_PATHS"
70+
android:resource="@xml/file_paths" />
71+
</provider>
72+
</application>
73+
```
74+
75+
创建 `Resources/xml/file_paths.xml`：
76+
77+
```xml
78+
<?xml version="1.0" encoding="utf-8"?>
79+
<paths>
80+
<cache-path name="cache" path="update/" />
81+
</paths>
82+
```
83+
84+
> **注意**：`authorities` 中的 `${applicationId}.fileprovider` 和代码中传入的 `FileProviderAuthority` 必须一致。
85+
86+
## Phase 3：编写更新代码
87+
88+
在 Avalonia ViewModel 或 Service 中集成更新逻辑：
89+
90+
```csharp
91+
using GeneralUpdate.Avalonia.Android;
92+
using GeneralUpdate.Avalonia.Android.Models;
93+
using GeneralUpdate.Avalonia.Android.Abstractions;
94+
95+
public class UpdateViewModel : ViewModelBase
96+
{
97+
private IAndroidBootstrap? _bootstrap;
98+
99+
public async Task CheckAndUpdateAsync()
100+
{
101+
// 1. 创建更新引导实例
102+
var options = new AndroidUpdateOptions
103+
{
104+
FileProviderAuthority = "com.myapp.fileprovider"
105+
};
106+
107+
_bootstrap = GeneralUpdateBootstrap.CreateDefault(options);
108+
109+
// 2. 订阅事件
110+
_bootstrap.AddListenerDownloadProgressChanged += (_, e) =>
111+
{
112+
// 更新 UI 进度条
113+
Console.WriteLine($"Download: {e.ProgressPercentage:F1}%");
114+
};
115+
116+
// 3. 构造更新包信息（通常从服务端获取）
117+
var package = new UpdatePackageInfo
118+
{
119+
Version = "2.0.0",
120+
DownloadUrl = "http://10.0.2.2:5000/packages/app-v2.0.0.apk",
121+
Sha256 = "服务端返回的SHA256哈希值",
122+
FileSize = 50_000_000,
123+
FileName = "app-v2.0.0.apk"
124+
};
125+
126+
// 4. 检查更新
127+
var checkResult = await _bootstrap.ValidateAsync(package, "1.0.0");
128+
if (!checkResult.UpdateFound)
129+
{
130+
Console.WriteLine("已是最新版本");
131+
return;
132+
}
133+
134+
// 5. 下载并校验
135+
var downloadResult = await _bootstrap.DownloadAndVerifyAsync(package);
136+
if (!downloadResult.Success)
137+
{
138+
Console.WriteLine($"下载失败: {downloadResult.Message}");
139+
return;
140+
}
141+
142+
// 6. 检查安装权限 (Android 8+)
143+
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.O)
144+
{
145+
var ctx = Android.App.Application.Context;
146+
var pm = ctx.PackageManager;
147+
if (pm != null && !pm.CanRequestPackageInstalls())
148+
{
149+
// 引导用户开启"安装未知应用"权限
150+
var intent = new Android.Content.Intent(
151+
Android.Provider.Settings.ActionManageUnknownAppSources)
152+
.SetData(Android.Net.Uri.Parse("package:" + ctx.PackageName));
153+
intent.AddFlags(Android.Content.ActivityFlags.NewTask);
154+
ctx.StartActivity(intent);
155+
return;
156+
}
157+
}
158+
159+
// 7. 启动安装器
160+
var installResult = await _bootstrap.LaunchInstallerAsync(
161+
package, downloadResult.FilePath!);
162+
163+
if (installResult.Success)
164+
Console.WriteLine("安装器已启动，请在设备上确认安装。");
165+
}
166+
}
167+
```
168+
169+
## Phase 4：启动 Server
170+
171+
使用 Samples 仓库中的 Server：
172+
173+
```bash
174+
git clone https://github.com/GeneralLibrary/GeneralUpdate-Samples.git
175+
cd GeneralUpdate-Samples/src/Server
176+
dotnet run
177+
```
178+
179+
Server 默认在 `http://localhost:5000` 启动。Android 模拟器中请使用 `http://10.0.2.2:5000` 访问宿主机的 localhost。
180+
181+
## Phase 5：端到端验证
182+
183+
1. 将 APK 包放到 `Server/wwwroot/packages/` 目录
184+
2. 更新 `wwwroot/packages/versions.json` 添加版本信息
185+
3. 在模拟器或真机上运行 Avalonia Android 应用
186+
4. 观察控制台输出：检查更新 → 下载 → 校验 → 启动安装器
187+
188+
### 预期输出
189+
190+
```
191+
Checking for updates...
192+
Update v2.0.0 found.
193+
Downloading... 45% 1.2MB/s
194+
Downloading... 100%
195+
SHA256 verified.
196+
Installer launched.
197+
```
198+
199+
## 下一步
200+
201+
- [GeneralUpdate.Avalonia.Android 组件文档](../doc/GeneralUpdate.Avalonia.Android)：完整 API 参考、配置说明和高级用法
202+
- [Android 更新示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/UI/AndroidUpdate)：完整的 Avalonia Android 更新示例项目

‎website/docs/quickstart/GeneralUpdate.PacketTool.md‎

Lines changed: 114 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ dotnet run --project GeneralUpdate.Tools.csproj
3232

3333
> Simulation 模块内部会调用 `dotnet publish` 构建测试应用，因此使用仿真功能时必须安装 .NET SDK，仅运行 Patch / Extension / OSS / Config 模块则不需要。
3434
35-
## 六个模块速览
35+
## 七个模块速览
3636

3737
| 模块 | 你提供 | 工具产出 | 下游消费者 |
3838
|------|--------|----------|------------|
@@ -42,6 +42,7 @@ dotnet run --project GeneralUpdate.Tools.csproj
4242
| **Config** | Client/Upgrade 的 `.csproj` | `generalupdate.manifest.json` + `sample_output/` 发布目录 | Client/Upgrade 启动引导 |
4343
| **Simulation** | 旧版本目录 + 补丁 ZIP | 本地更新服务 + `simulation_report.md` | 发布前质量把关 |
4444
| **Hash** | 本地文件（ZIP） | SHA256 小写十六进制字符串 | 完整性校验、服务端版本记录 |
45+
| **Mobile** | APK/AAB 文件或 MAUI/Avalonia Android 的 `.csproj` | `mobile_version_{timestamp}.json` 版本记录 | 移动端更新服务端、GeneralUpdate.Avalonia/Maui 组件 |
4546

4647
---
4748

@@ -325,9 +326,103 @@ Generate Sample 额外输出：
325326

326327
---
327328

329+
## Mobile：移动端打包
330+
331+
### 解决什么问题
332+
333+
如果你使用 `GeneralUpdate.Avalonia.Android` 或 `GeneralUpdate.Maui.Android` 组件为 Android 应用提供自动更新能力，每次发布新版本时都需要获取 APK/AAB 文件的元数据（包名、版本号、SHA256 哈希、文件大小），并将其上传到服务端进行版本管理。Mobile 模块把"解析 → 打包 → 上传 → 生成版本记录"这四步收敛到一个界面中。
334+
335+
支持两种工作模式：
336+
337+
- **文件模式**：直接选择 APK 或 AAB 文件，自动解析 AndroidManifest.xml 提取元数据
338+
- **项目模式**：选择 `.csproj` 项目文件，自动执行 `dotnet publish` 构建，然后定位产物并解析
339+
340+
### 输入
341+
342+
#### 文件模式
343+
344+
| 字段 | 必填 | 说明 |
345+
|------|------|------|
346+
| APK/AAB 文件 | ✅ | 选择 `.apk` 或 `.aab` 文件，工具自动识别格式类型 |
347+
| Output Directory | ❌ | 版本记录 JSON 输出目录，为空时输出到桌面 |
348+
| ProductId | ✅ | 产品标识 GUID，用于区分服务端产品线 |
349+
| Platform | ✅ | 目标平台（默认 Android = 4） |
350+
| Product Name | ❌ | 产品名称，写入版本记录 |
351+
| Release Notes | ❌ | 发布说明 |
352+
| Is Forcibly | ❌ | 是否强制更新 |
353+
354+
#### 项目模式
355+
356+
| 字段 | 必填 | 说明 |
357+
|------|------|------|
358+
| `.csproj` 文件 | ✅ | 选择 MAUI 或 Avalonia Android 项目的 `.csproj`，工具自动解析 `ApplicationId`、`ApplicationDisplayVersion`、`ApplicationVersion` |
359+
| Output Directory | ❌ | 同上 |
360+
361+
### 操作流程
362+
363+
1. **选择模式**：切换 File Mode / Project Mode 开关。
364+
- **文件模式**：点击 **Select File** 选择 `.apk` 或 `.aab` 文件。
365+
- **项目模式**：点击 **Select Project** 选择 `.csproj` 文件，然后点击 **Build & Locate** 自动执行 `dotnet publish` 并定位产物。
366+
2. **Analyze**：点击 Analyze 按钮，工具自动：
367+
- 识别文件格式（APK / Android App Bundle）
368+
- 从 AndroidManifest.xml 中提取 `PackageName`、`VersionName`、`VersionCode`
369+
- 计算 SHA256 哈希和文件大小
370+
3. **填写上传配置**：确认或编辑自动提取的元数据，填写 ProductId、Product Name 等发布信息。
371+
4. **Upload**：点击 Upload 上传到服务端，并自动生成版本记录 JSON 文件。
372+
373+
### 工具内部做了什么
374+
375+
1. **格式检测**：通过文件扩展名（`.apk` / `.aab`）和 ZIP 内部结构（`AndroidManifest.xml` 位置）自动识别包格式。
376+
2. **元数据解析**：使用 `AxmlParser` 从 ZIP 中读取二进制的 `AndroidManifest.xml`，提取 `package`、`versionName`、`versionCode`。
377+
3. **SHA256 计算**：对完整文件计算 SHA256 哈希值。
378+
4. **文件大小**：读取文件长度并格式化为人类可读的显示（KB/MB/GB）。
379+
5. **项目构建**（仅项目模式）：调用 `dotnet publish -c Release -o {publishDir}`，自动定位输出的 APK/AAB 文件。
380+
6. **上传**：通过 HTTP multipart/form-data 将文件和表单字段（Name、Version、Hash、Format、Size、Platform、ProductId、IsForcibly）上传到服务端。
381+
7. **版本记录导出**：上传成功后生成 `mobile_version_{timestamp}.json`，包含完整的版本元数据。
382+
383+
### 输出
384+
385+
```
386+
{OutputDirectory}/mobile_version_20260614120000.json
387+
```
388+
389+
```json
390+
{
391+
"name": "MyApp",
392+
"version": "2.0.0",
393+
"hash": "a1b2c3d4e5f6...",
394+
"url": "https://server.example.com/packages/app-v2.0.0.apk",
395+
"packageName": "com.example.myapp",
396+
"fileSize": 50000000,
397+
"format": "apk",
398+
"platform": 4,
399+
"productId": "2d974e2a-31e6-4887-9bb1-b4689e98c77a",
400+
"isForcibly": false,
401+
"releaseDate": "2026-06-14T12:00:00.0000000Z"
402+
}
403+
```
404+
405+
### 下游如何使用
406+
407+
- 将生成的版本记录 JSON 导入或上传到你的更新服务端（如 GeneralSpacestation）
408+
- 客户端（`GeneralUpdate.Avalonia.Android` 或 `GeneralUpdate.Maui.Android`）从服务端查询版本信息时，返回的数据结构与版本记录的内容对应
409+
- 客户端下载 APK 后使用 `hash` 字段做 SHA256 完整性校验
410+
411+
### 支持的 AndroidManifest 字段提取
412+
413+
| 清单属性 | 字段名 | 说明 |
414+
|---------|--------|------|
415+
| `package` | `PackageName` | 应用包名（唯一标识） |
416+
| `android:versionName` | `VersionName` | 展示版本号（如 `2.0.0`） |
417+
| `android:versionCode` | `VersionCode` | 内部版本代码（整数） |
418+
419+
---
420+
328421
## 推荐发布工作流
329422

330-
这个顺序把六个模块串联成一个完整的发布流水线：
423+
### 桌面端更新
424+
425+
这个顺序把 Patch、OSS、Config、Simulation 四个模块串联成一个完整的桌面应用发布流水线：
331426

332427
```
333428
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
@@ -343,6 +438,21 @@ Generate Sample 额外输出：
343438
5. **Simulation**：选择旧版本目录和补丁 ZIP，确认 PASS。
344439
6. **发布上线**：上传补丁 ZIP、OSS 清单到生产环境。
345440

441+
### 移动端更新
442+
443+
使用 Mobile 模块串联移动端 Android 应用发布：
444+
445+
```
446+
┌────────────┐ ┌──────────┐ ┌──────────┐
447+
│ 构建 APK/ │ -> │ Mobile │ -> │ 发布上线 │
448+
│ AAB 产物 │ │ 解析+上传 │ │ 更新服务 │
449+
└────────────┘ └──────────┘ └──────────┘
450+
```
451+
452+
1. **构建产物**：在 CI 或本地构建出 `.apk` / `.aab` 文件。
453+
2. **Mobile**：选择文件或项目，自动解析元数据、计算 SHA256、上传服务端、导出版本记录。
454+
3. **发布上线**：确认上传成功，客户端通过 `GeneralUpdate.Avalonia.Android` 或 `GeneralUpdate.Maui.Android` 检查更新。
455+
346456
---
347457

348458
## 常见问题
@@ -364,4 +474,6 @@ Generate Sample 额外输出：
364474
- [GeneralUpdate.Core](../doc/GeneralUpdate.Core)：Client/Upgrade 更新主流程
365475
- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential)：差分算法 Clean/Dirty 模式
366476
- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension)：扩展包安装与版本管理
477+
- [GeneralUpdate.Avalonia.Android](../doc/GeneralUpdate.Avalonia.Android)：Avalonia Android APK 更新组件
478+
- [GeneralUpdate.Maui.Android](../doc/GeneralUpdate.Maui.Android)：MAUI Android APK 更新组件
367479
- [入门实战手册](./Beginner%20cookbook)：从零跑通完整更新闭环

0 commit comments

Comments
 (0)