Generalupdate migration

GeneralUpdate Migration Guide / GeneralUpdate 迁移指南

<!-- generalupdate-runtime-contract:v10.5.0-rc.1 -->

Mandatory Runtime Contract

Apply the repository RULES.md when available. Otherwise: respond in exactly one language selected from the user's explicit choice, then dominant intent (mixed-input tie: latest complete sentence); keep identifiers unchanged. User format wins; otherwise use compact output for lightweight/unknown agents, numbered evidence and fixes for debugging agents, and complete artifacts for professional R&D agents. Apply platform safety → user constraints → v10.5 contract → this workflow → presentation defaults; security, compilability, and scope win conflicts. Generate only v10.5.0-rc.1 desktop APIs (UpdateRequest/SetConfig or SetSource, then LaunchAsync; enum AppType); never generate Configinfo or IsComplated. Use Core alone for Core scenarios, Bowl alone for Bowl scenarios, no separate Differential package, and the matching mobile package. Use native tool schemas, one operation per call, no secrets, at most 20 paths/results, and queries of at most 500 characters. Deliver only relevant runnable artifacts, exact steps, warnings, and checks; never claim unexecuted verification or present pseudo-code as production-ready.

This skill migrates older integrations to NuGet v10.5.0-rc.1. It may quote legacy identifiers only to identify code that must be removed; generated replacement code always uses the v10.5.0-rc.1 specification.

本技能将旧版集成迁移到 NuGet v10.5.0-rc.1。旧标识符仅用于定位待删除代码； 生成的替换代码始终使用 v10.5.0-rc.1 规范。

Pre-Migration Information / 迁移前信息

Collect these fields before choosing a path:

在选择迁移路径前收集：

- Current GeneralUpdate version / 当前版本: ______
- .NET version / .NET 版本: ______
- UI framework and OS / UI 框架与系统: ______
- Client + Upgrade projects present / 是否已有 Client + Upgrade: ______
- Bowl, Differential, OSS, Hooks, custom IPC / 已用扩展: ______
- Current build error or runtime symptom / 当前错误或症状: ______

Do not guess the source version. If it is unknown, inspect package references, configuration type names, manifest files, and Bootstrap calls first.

不要猜测源版本。版本未知时，先检查包引用、配置类型、manifest 和 Bootstrap 调用。

Migration Paths / 迁移路径

Path A: v9.x → v10.5.0-rc.1

This is an architecture migration:

这是架构迁移：

single process                     → Client + Upgrade processes
direct updater call                → GeneralUpdateBootstrap.LaunchAsync()
legacy URL/method setters          → UpdateRequest or SetSource()
no required manifest              → generalupdate.manifest.json
legacy event callbacks             → AddListener* event registration

Required order:

1. Create independent Client and Upgrade projects.
2. Pin the selected package to 10.5.0-rc.1 in both roles.
3. Add and deploy a valid manifest with the first release.
4. Replace legacy configuration with UpdateRequest.
5. Register only the listeners needed by the application.
6. Build and run both processes, then test a complete update and restart.

必须按以上顺序完成双进程、包版本、manifest、配置、事件和端到端验证。

Path B: v10.4.6 → v10.5.0-rc.1

Keep the dual-process structure, then make these API replacements:

保留双进程结构，并替换以下 API：

v10.4.6 source / 源代码	v10.5.0-rc.1 replacement / 替换项
Legacy configuration object	UpdateRequest in GeneralUpdate.Core.Configuration
Configuration URL/key fields	SetSource(updateUrl, appSecretKey) or SetConfig(request)
Ad-hoc silent flags	SetOption(Option.Silent, true)
Event-based lifecycle workarounds	Hooks<T>() with IUpdateHooks
Hard-wired custom flow	Strategy<T>() with IStrategy
Manual diff setup	UseDiffPipeline(...); Differential remains embedded in Core
Completed-event typo	MultiDownloadCompletedEventArgs.IsCompleted
Numeric role constants	AppType.Client, Upgrade, OssClient, or OssUpgrade

Remove old package references before restoring. Core scenarios reference Core alone; Bowl scenarios reference Bowl alone. Do not add a Differential package.

恢复包之前先删除旧引用。Core 场景仅引用 Core，Bowl 场景仅引用 Bowl，不添加 Differential 包。

v10.5.0-rc.1 Replacement Code / v10.5.0-rc.1 替换代码

using GeneralUpdate.Core;
using GeneralUpdate.Core.Configuration;

var request = new UpdateRequest
{
    UpdateUrl = "https://updates.example.com/Upgrade/Verification",
    AppSecretKey = Environment.GetEnvironmentVariable("GENERALUPDATE_APP_KEY")
        ?? throw new InvalidOperationException("GENERALUPDATE_APP_KEY is required."),
    MainAppName = "MyApp.exe",
    ClientVersion = "1.0.0.0",
    ProductId = "my-product-001",
    InstallPath = AppDomain.CurrentDomain.BaseDirectory
};

await new GeneralUpdateBootstrap()
    .SetConfig(request)
    .AddListenerUpdateInfo((_, e) => Console.WriteLine(e.Info))
    .AddListenerException((_, e) => Console.Error.WriteLine(e.Message))
    .LaunchAsync();

Use SetSource(...) only when the manifest supplies the remaining identity and path values. Never hardcode a production secret.

仅当 manifest 提供其余身份和路径字段时使用 SetSource(...)。生产密钥不得硬编码。

Migration Verification Checklist / 迁移验证清单

Static / 静态检查

• Every GeneralUpdate package is pinned to 10.5.0-rc.1.
• Generated code uses UpdateRequest, SetConfig/SetSource, and LaunchAsync.
• No active legacy configuration object or completed-event typo remains.
• AppType uses v10.5.0-rc.1 enum members.
• Core/Bowl are not combined; no Differential package is referenced.
• Namespaces match the v10.5.0-rc.1 event and configuration types.

Build and Runtime / 构建与运行

• Restore and build Client and Upgrade with zero errors.
• Validate generalupdate.manifest.json and four-part versions.
• Confirm the verification endpoint returns the selected app role.
• Test download, hash verification, replacement, restart, and write-back.
• Test failure reporting and rollback/crash handling when configured.
• Verify UTF-8 and executable permissions on Linux/macOS.

Migration Anti-Patterns / 迁移反模式

Anti-pattern / 反模式	Required correction / 正确做法
Updating only the package version / 只改包版本	Replace APIs first, then restore and build / 先替换 API 再恢复构建
Mixing old and new configuration / 混用新旧配置	Generate only UpdateRequest or SetSource / 仅生成新配置
Migrating only Client / 只迁移 Client	Build and test Client + Upgrade / 同时构建测试两端
Combining Core and Bowl / 同时引用 Core 和 Bowl	Select one package for that project / 每个项目选择一个包
Adding Differential NuGet / 添加差分包	Use Core's embedded diff pipeline / 使用 Core 内嵌差分管道
Claiming success after compilation only / 编译后即宣称成功	Run an end-to-end update and restart / 执行端到端更新重启

Related Skills / 相关技能

• /generalupdate-init — Generate the v10.5.0-rc.1 baseline / 生成新版基线
• /generalupdate-troubleshoot — Diagnose migration failures / 诊断迁移失败
• /generalupdate-security-audit — Audit production deployment / 审计生产部署