sidebar_position	10

GeneralUpdate.Maui.Android

命名空间: GeneralUpdate.Maui.Android | 主要入口: GeneralUpdateBootstrap.CreateDefault() / AddGeneralUpdateMauiAndroid() | NuGet 包: GeneralUpdate.Maui.Android

1. 组件简介

1.1 组件概述

GeneralUpdate.Maui.Android 是面向 .NET MAUI 应用的 Android 平台自动更新组件，为 Android APK 提供版本发现、可恢复下载、SHA256 完整性校验以及系统 Package Installer 触发的一站式更新编排。

与桌面应用的文件替换式更新不同，Android APK 更新必须经由系统 Package Installer 完成。该组件封装了这一平台差异，并提供两阶段 API：ValidateAsync 做版本检查，ExecuteUpdateAsync 串起下载→校验→安装的完整流程。

核心能力：

能力	说明
版本对比检查	内置 `System.Version` 解析，自动判断当前版本是否低于目标版本
可恢复 APK 下载	`HttpRangeDownloader` 基于 HTTP Range 请求头实现断点续传，支持进度报告
SHA256 完整性校验	下载后自动计算文件 SHA256 与服务端哈希比对，损坏文件自动删除
系统安装器触发	`AndroidApkInstaller` 通过 FileProvider + Intent 启动系统 Package Installer
DI 容器集成	`AddGeneralUpdateMauiAndroid()` 扩展方法一键注册所有服务到 `IServiceCollection`
HTTP 传输配置	`HttpDownloadOptions` 支持 SSL 证书策略、代理、超时、认证，支持指数退避重试
多协议认证	支持 HMAC-SHA256、Bearer Token、API Key、HTTP Basic 四种认证方案
事件通知	版本发现、下载进度、完成阶段、失败原因等全方位事件
并发安全	`ExecuteUpdateAsync` 内置 `Interlocked` 并发保护，重复调用直接返回 `AlreadyInProgress`
临时文件管理	下载使用 `.downloading` 临时扩展名，完成后原子替换为目标文件

解决的业务痛点：

MAUI Android 应用需要内置自动更新能力，但 APK 安装必须绕过 Google Play 通过系统安装器完成
大 APK 下载过程中网络不稳定，需要断点续传减少用户流量消耗
需要确保下载的 APK 未被篡改或损坏，保障更新安全
需要与 MAUI 的 DI 容器深度集成，简化接入代码

:::info MAUI 更新 ≠ 桌面文件替换 Android 平台无法像桌面端那样直接替换可执行文件。APK 必须通过 Android Package Installer 安装，系统会处理签名验证和应用替换。MAUI 组件封装了这一差异，但 APK 签名、版本号递增 仍然需要你在构建流水线中保证。 :::

业务使用场景：

MAUI Android 应用的自动更新（企业内部分发、Beta 测试、旁加载）
需要通过 CDN / OSS 分发 APK 包的应用
需要 DI 容器管理的 MAUI 应用

1.2 环境与依赖

项目	说明
NuGet 包	`GeneralUpdate.Maui.Android`
目标框架	`net10.0` + `net10.0-android`（多目标；Android 最低 API 21）
依赖包	`Microsoft.Extensions.DependencyInjection.Abstractions`、`Microsoft.Extensions.Http`、`Xamarin.AndroidX.Core`
兼容性	Android 5.0 (API 21) 及以上版本

2. 组件功能列表

功能名称	功能描述	类型	是否必填	备注限制
版本对比检查	对比当前版本与目标版本，判断是否有更新可用	基础	必选	`ValidateAsync`，基于 `System.Version` 解析
更新执行	串起下载→校验→安装全流程	基础	必选	`ExecuteUpdateAsync`，并发保护
APK 可恢复下载	HTTP Range 断点续传 + 进度报告	基础	自动	`HttpRangeDownloader`
SHA256 校验	下载后自动校验，损坏文件自动删除	基础	自动	通过 `IHashValidator`，支持进度回调
APK 安装触发	FileProvider + Intent 启动系统安装器	基础	自动	`AndroidApkInstaller`，自动检查安装权限
DI 容器集成	一键注册所有更新服务	拓展	推荐	`AddGeneralUpdateMauiAndroid()`
HTTP 传输配置	SSL、代理、超时、重试、认证	拓展	可选	`HttpDownloadOptions`
多协议认证	HMAC-SHA256 / Bearer / API Key / Basic	拓展	可选	全局或单包粒度配置
进度通知	下载字节数、速度、百分比、剩余时间	基础	可选	`IProgress<DownloadStatistics>` 回调
完成通知	各完成阶段（下载完成、校验完成、安装触发、工作流完成）	基础	可选	`AddListenerUpdateCompleted`
失败通知	失败原因分类、异常信息	基础	可选	`AddListenerUpdateFailed`
验证通知	发现可用更新时触发	基础	可选	`AddListenerValidate`
状态查询	实时查询当前更新状态	基础	可选	`CurrentState` 属性
并发保护	防止重复执行更新操作	基础	自动	`Interlocked` 原子操作
损坏文件自动清理	校验失败自动删除损坏包	拓展	可选	`UpdateOptions.DeleteCorruptedPackageOnFailure`
进度报告间隔控制	自定义进度回调频率	拓展	可选	`UpdateOptions.ProgressReportInterval`
自定义下载器	自定义下载实现	拓展	可选	实现 `IUpdateDownloader`
自定义哈希验证	自定义哈希实现	拓展	可选	实现 `IHashValidator`
自定义安装器	自定义安装逻辑	拓展	可选	实现 `IApkInstaller`
自定义存储提供器	自定义文件路径和存储操作	拓展	可选	实现 `IUpdateStorageProvider`
自定义日志	自定义日志输出	拓展	可选	实现 `IUpdateLogger`
自定义 SSL 策略	自定义 HTTPS 证书校验	拓展	可选	实现 `ISslValidationPolicy`
自定义 HTTP 认证	自定义 HTTP 请求认证	拓展	可选	实现 `IHttpAuthProvider`

3. API 配置说明

3.1 配置字段（属性 Props）

UpdateOptions：

字段名	数据类型	默认值	是否必填	说明
`CurrentVersion`	`string`	`""`	是	当前应用版本号
`DownloadDirectory`	`string?`	`null`	可选	下载目录，为空时自动选择
`TemporaryFileExtension`	`string`	`".downloading"`	可选	临时下载文件扩展名
`DeleteCorruptedPackageOnFailure`	`bool`	`true`	可选	校验失败时自动删除损坏包
`ProgressReportInterval`	`TimeSpan`	`500ms`	可选	进度报告间隔
`InstallOptions`	`AndroidInstallOptions`	`new()`	可选	安装选项

AndroidInstallOptions：

字段名	数据类型	默认值	是否必填	说明
`FileProviderAuthority`	`string`	`""`	是	FileProvider authority，需与 AndroidManifest 一致
`MimeType`	`string`	`"application/vnd.android.package-archive"`	可选	APK 文件的 MIME 类型

HttpDownloadOptions：

字段名	数据类型	默认值	是否必填	说明
`SslValidationPolicy`	`ISslValidationPolicy?`	`null`	可选	自定义 SSL 证书验证策略
`DownloadTimeout`	`TimeSpan`	`10min`	可选	整体下载超时
`Proxy`	`IWebProxy?`	`null`	可选	HTTP 代理
`UseProxy`	`bool`	`false`	可选	是否启用代理
`AuthProvider`	`IHttpAuthProvider?`	`null`	可选	全局 HTTP 认证提供器

UpdatePackageInfo：

字段名	数据类型	默认值	是否必填	说明
`Version`	`string`	`""`	是	目标版本号
`DownloadUrl`	`string`	`""`	是	APK 下载地址
`Sha256`	`string`	`""`	是	SHA256 哈希值
`PackageSize`	`long?`	`null`	可选	包大小（字节）
`ApkFileName`	`string?`	`null`	可选	APK 文件名
`ForceUpdate`	`bool`	`false`	可选	是否强制更新
`VersionName`	`string?`	`null`	可选	展示名称
`ReleaseNotes`	`string?`	`null`	可选	发布说明
`PublishTime`	`DateTimeOffset?`	`null`	可选	发布时间
`AuthScheme`	`AuthScheme?`	`null`	可选	认证方案
`AuthToken`	`string?`	`null`	可选	认证令牌
`AuthSecretKey`	`string?`	`null`	可选	HMAC 密钥
`BasicUsername`	`string?`	`null`	可选	Basic 用户名
`BasicPassword`	`string?`	`null`	可选	Basic 密码

UpdateState 枚举：

枚举值	说明
`None`	初始/空闲状态
`Checking`	正在检查更新
`UpdateAvailable`	发现可用更新
`Downloading`	正在下载
`Verifying`	正在校验
`ReadyToInstall`	准备安装
`Installing`	正在安装
`Completed`	更新完成
`Failed`	更新失败
`Canceled`	已取消

UpdateFailureReason 枚举：

枚举值	说明
`Unknown`	未知错误
`InvalidInput`	输入参数无效
`AlreadyInProgress`	已有更新操作正在进行
`Network`	网络错误
`Download`	下载错误
`FileAccess`	文件访问错误
`IntegrityCheckFailed`	完整性校验失败
`InstallPermissionDenied`	安装权限被拒绝
`Installation`	安装过程错误
`Canceled`	用户取消
`NoUpdateAvailable`	无可用更新

UpdateCompletionStage 枚举：

枚举值	说明
`DownloadCompleted`	下载完成
`VerificationCompleted`	校验完成
`InstallationTriggered`	安装器已启动
`WorkflowCompleted`	工作流完成

3.2 实例方法

GeneralUpdateBootstrap（静态工厂）：

方法名	入参明细	使用场景	注意事项
`CreateDefault(HttpClient?, IUpdateLogger?, HttpDownloadOptions?)`	`httpClient` — 可选外部 HttpClient；`logger` — 可选日志器；`httpOptions` — 可选 HTTP 配置	创建默认的 Android 更新引导实例	`httpOptions` 生效时 `httpClient` 参数被忽略
`AddGeneralUpdateMauiAndroid(IServiceCollection, HttpClient?)`	`services` — DI 容器；`httpClient` — 可选外部 HttpClient	在 MAUI DI 容器中注册所有更新服务	返回 `IServiceCollection` 支持链式调用

IAndroidBootstrap：

方法名	入参明细	使用场景	注意事项
`ValidateAsync(UpdatePackageInfo, UpdateOptions, CancellationToken)`	`packageInfo` — 更新包信息；`options` — 更新选项；`ct` — 取消令牌	检查是否有可用的更新	返回 `UpdateCheckResult`，包含 `IsUpdateAvailable`
`ExecuteUpdateAsync(UpdatePackageInfo, UpdateOptions, CancellationToken)`	`packageInfo` — 更新包信息；`options` — 更新选项；`ct` — 取消令牌	执行完整更新：下载→校验→安装	内置并发保护，重复调用返回 `AlreadyInProgress`
`Dispose()`	无	释放下载器等资源	—
`CurrentState`	属性（`UpdateState`）	查询当前更新状态	线程安全（`Volatile.Read`）

3.3 回调事件

事件名称	回调参数	触发时机	使用说明
`AddListenerValidate`	`ValidateEventArgs` — `PackageInfo`	版本对比完成，发现可用更新时	可用于 UI 展示新版本信息
`AddListenerDownloadProgressChanged`	`DownloadProgressChangedEventArgs` — `PackageInfo`, `Statistics`（`DownloadProgressInfo`：`ProgressPercentage`, `DownloadedBytes`, `TotalBytes`, `BytesPerSecond`, `RemainingBytes`）, `StatusDescription`	下载进度更新时	通过 `IProgress<DownloadStatistics>` 回调
`AddListenerUpdateCompleted`	`UpdateCompletedEventArgs` — `PackageInfo`, `Stage`（`UpdateCompletionStage`）, `PackagePath`	各阶段完成时	分为下载完成、校验完成、安装触发、工作流完成四个阶段
`AddListenerUpdateFailed`	`UpdateFailedEventArgs` — `Reason`, `Message`, `Exception`, `PackageInfo`	任何阶段失败时	包含结构化的失败原因

4. 扩展示例（高阶用法）

4.1 组件可扩展能力总览

所有服务可通过 AddGeneralUpdateMauiAndroid() 注册后，通过 DI 容器替换：

接口	默认实现	说明
`IUpdateDownloader`	`HttpRangeDownloader`	可恢复 APK 下载
`IHashValidator`	`Sha256Validator`	SHA256 哈希校验
`IApkInstaller`	`AndroidApkInstaller`	APK 安装触发
`IUpdateStorageProvider`	`UpdateFileStore`	文件路径和存储操作
`IUpdateLogger`	`NullUpdateLogger`	日志记录器
`IUpdateBootstrap`	`AndroidBootstrap`	更新编排（通过 DI 注册）
`ISslValidationPolicy`	通过 `HttpDownloadOptions` 配置	SSL 证书验证策略
`IHttpAuthProvider`	通过 `HttpDownloadOptions` 或单包配置	HTTP 认证提供器

4.2 分场景示例

场景 1：DI 容器集成

【场景说明】在 MAUI 应用中将更新服务注册到 DI 容器，便于管理和测试。

using GeneralUpdate.Maui.Android.Abstractions;
using GeneralUpdate.Maui.Android.Models;
using GeneralUpdate.Maui.Android.Services;
using Microsoft.Extensions.Logging;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts => { });

        // 注册更新服务
        builder.Services.AddGeneralUpdateMauiAndroid();
        
        // 注册应用服务
        builder.Services.AddSingleton<MainViewModel>();
        builder.Services.AddSingleton<MainPage>();

        return builder.Build();
    }
}

// 在 ViewModel 中使用
public class MainViewModel
{
    private readonly IAndroidBootstrap _bootstrap;

    public MainViewModel(IAndroidBootstrap bootstrap)
    {
        _bootstrap = bootstrap;
        WireEvents();
    }

    public async Task CheckAndUpdateAsync()
    {
        var package = new UpdatePackageInfo
        {
            Version = "2.0.0",
            DownloadUrl = "https://example.com/app-v2.apk",
            Sha256 = "expected-sha256"
        };

        var options = new UpdateOptions
        {
            CurrentVersion = "1.0.0",
            InstallOptions = new AndroidInstallOptions
            {
                FileProviderAuthority = "com.myapp.fileprovider"
            }
        };

        var result = await _bootstrap.ExecuteUpdateAsync(package, options, CancellationToken.None);
        Console.WriteLine(result.IsSuccess ? "Update succeeded!" : $"Failed: {result.Message}");
    }

    private void WireEvents()
    {
        _bootstrap.AddListenerDownloadProgressChanged += (_, args) =>
        {
            Console.WriteLine($"Progress: {args.Statistics.ProgressPercentage:F1}%");
        };
    }
}

场景 2：自定义 HTTP 认证

【场景说明】企业内部分发的 APK 需要 Bearer Token 认证。

using GeneralUpdate.Maui.Android.Abstractions;
using GeneralUpdate.Maui.Android.Models;
using GeneralUpdate.Maui.Android.Services;

// 方式一：使用全局认证提供器
var httpOptions = new HttpDownloadOptions
{
    AuthProvider = new Services.BearerTokenAuthProvider("your-token-here")
};

var bootstrap = GeneralUpdateBootstrap.CreateDefault(
    httpClient: null,
    logger: null,
    httpOptions: httpOptions);

// 方式二：使用单包认证
var package = new UpdatePackageInfo
{
    Version = "2.0.0",
    DownloadUrl = "https://example.com/app-v2.apk",
    Sha256 = "expected-sha256",
    AuthScheme = Enums.AuthScheme.Bearer,
    AuthToken = "your-token-here"
};

场景 3：非容器环境下的直接使用

【场景说明】简单应用不依赖 DI 容器，直接使用静态工厂创建。

using GeneralUpdate.Maui.Android;
using GeneralUpdate.Maui.Android.Models;

// 直接创建
var bootstrap = GeneralUpdateBootstrap.CreateDefault();

// 配置更新选项
var options = new UpdateOptions
{
    CurrentVersion = "1.0.0",
    InstallOptions = new AndroidInstallOptions
    {
        FileProviderAuthority = "com.myapp.fileprovider"
    }
};

var package = new UpdatePackageInfo
{
    Version = "2.0.0",
    DownloadUrl = "https://example.com/app-v2.apk",
    Sha256 = "expected-sha256",
    PackageSize = 50_000_000,
    ApkFileName = "app-v2.apk"
};

// 执行更新
var result = await bootstrap.ExecuteUpdateAsync(package, options, CancellationToken.None);

5. 常规使用示例

5.1 快速入门示例（最简 demo）

using GeneralUpdate.Maui.Android;
using GeneralUpdate.Maui.Android.Models;

// 创建实例
var bootstrap = GeneralUpdateBootstrap.CreateDefault();

// 更新包信息（通常从服务端 API 获取）
var package = new UpdatePackageInfo
{
    Version = "2.0.0",
    DownloadUrl = "https://update.example.com/app-v2.0.0.apk",
    Sha256 = "a1b2c3d4e5f6..." // 服务端返回的 SHA256
};

// 更新选项
var options = new UpdateOptions
{
    CurrentVersion = "1.0.0",
    InstallOptions = new AndroidInstallOptions
    {
        FileProviderAuthority = "com.myapp.fileprovider"
    }
};

// 检查更新
var checkResult = await bootstrap.ValidateAsync(package, options, CancellationToken.None);
if (!checkResult.IsUpdateAvailable)
{
    Console.WriteLine("Already up to date.");
    return;
}

// 执行更新（下载 → 校验 → 安装）
var result = await bootstrap.ExecuteUpdateAsync(package, options, CancellationToken.None);
Console.WriteLine(result.IsSuccess ? "Update completed." : $"Update failed: {result.Message}");

5.2 基础参数组合示例

using GeneralUpdate.Maui.Android;
using GeneralUpdate.Maui.Android.Enums;
using GeneralUpdate.Maui.Android.Models;

var httpOptions = new HttpDownloadOptions
{
    DownloadTimeout = TimeSpan.FromMinutes(30),
    AuthProvider = new GeneralUpdate.Maui.Android.Services.BearerTokenAuthProvider("token")
};

var bootstrap = GeneralUpdateBootstrap.CreateDefault(
    httpClient: null,
    logger: null,
    httpOptions: httpOptions);

// 事件监听
bootstrap.AddListenerDownloadProgressChanged += (_, e) =>
{
    var s = e.Statistics;
    Console.WriteLine($"Progress: {s.ProgressPercentage:F1}% | " +
                      $"{FormatSize(s.DownloadedBytes)}/{FormatSize(s.TotalBytes)} | " +
                      $"{FormatSpeed(s.BytesPerSecond)}");
};

bootstrap.AddListenerUpdateCompleted += (_, e) =>
{
    Console.WriteLine($"Stage completed: {e.Stage}");
};

bootstrap.AddListenerUpdateFailed += (_, e) =>
{
    Console.WriteLine($"Failed: {e.Reason} — {e.Message}");
};

var options = new UpdateOptions
{
    CurrentVersion = "1.0.0",
    TemporaryFileExtension = ".downloading",
    DeleteCorruptedPackageOnFailure = true,
    ProgressReportInterval = TimeSpan.FromMilliseconds(250),
    InstallOptions = new AndroidInstallOptions
    {
        FileProviderAuthority = "com.myapp.fileprovider"
    }
};

var package = new UpdatePackageInfo
{
    Version = "2.0.0",
    DownloadUrl = "https://cdn.example.com/app-v2.0.0.apk",
    Sha256 = "expected-sha256",
    PackageSize = 50_000_000,
    ApkFileName = "app-v2.0.0.apk",
    ForceUpdate = false,
    ReleaseNotes = "Bug fixes and performance improvements"
};

var result = await bootstrap.ExecuteUpdateAsync(package, options, CancellationToken.None);

if (!result.IsSuccess)
{
    Console.WriteLine($"Update failed: {result.FailureReason}");
}

// 辅助方法
static string FormatSize(long bytes) => bytes switch
{
    < 1024 => $"{bytes} B",
    < 1048576 => $"{bytes / 1024.0:F1} KB",
    _ => $"{bytes / 1048576.0:F1} MB"
};

static string FormatSpeed(double bytesPerSecond) =>
    $"{bytesPerSecond / 1048576.0:F1} MB/s";

5.3 真实业务落地示例

完整 MAUI Android 更新工作流，包含服务端 API 对接、事件处理和错误分类：

using GeneralUpdate.Maui.Android;
using GeneralUpdate.Maui.Android.Abstractions;
using GeneralUpdate.Maui.Android.Enums;
using GeneralUpdate.Maui.Android.Models;
using System.Net.Http.Json;

public sealed class MauiUpdateService : IDisposable
{
    private readonly HttpClient _httpClient;
    private IAndroidBootstrap? _bootstrap;
    private readonly string _fileProviderAuthority;
    private bool _disposed;

    public MauiUpdateService(HttpClient httpClient, string fileProviderAuthority)
    {
        _httpClient = httpClient;
        _fileProviderAuthority = fileProviderAuthority;
    }

    // 初始化（接收 HttpDownloadOptions 实现可选认证）
    public void Initialize(HttpDownloadOptions? httpOptions = null)
    {
        _bootstrap = GeneralUpdateBootstrap.CreateDefault(
            httpClient: null,
            logger: null,
            httpOptions: httpOptions);
        WireEvents();
    }

    // 从服务端获取更新包信息并执行更新
    public async Task<UpdateResult> CheckAndUpdateAsync(
        string serverUrl, string currentVersion,
        CancellationToken ct = default)
    {
        if (_bootstrap == null)
            throw new InvalidOperationException("Call Initialize() first.");

        try
        {
            // 1. 从服务端获取更新包信息
            var package = await FetchPackageFromServerAsync(serverUrl, currentVersion, ct);
            if (package == null)
                return UpdateResult.NoUpdate();

            // 2. 检查版本
            var options = new UpdateOptions
            {
                CurrentVersion = currentVersion,
                InstallOptions = new AndroidInstallOptions
                {
                    FileProviderAuthority = _fileProviderAuthority
                }
            };

            var checkResult = await _bootstrap.ValidateAsync(package, options, ct);
            if (!checkResult.IsUpdateAvailable)
                return UpdateResult.NoUpdate();

            // 3. 执行更新
            var execResult = await _bootstrap.ExecuteUpdateAsync(package, options, ct);

            return execResult.IsSuccess
                ? UpdateResult.Success()
                : UpdateResult.Failure(execResult.FailureReason, execResult.Message);
        }
        catch (OperationCanceledException)
        {
            return UpdateResult.Canceled();
        }
        catch (HttpRequestException ex)
        {
            return UpdateResult.Failure(UpdateFailureReason.Network, ex.Message);
        }
    }

    private async Task<UpdatePackageInfo?> FetchPackageFromServerAsync(
        string serverUrl, string currentVersion, CancellationToken ct)
    {
        // 调用服务端版本检查 API
        var request = new
        {
            Version = currentVersion,
            AppType = 1,
            Platform = 4,
            ProductId = "your-product-id"
        };

        var response = await _httpClient.PostAsJsonAsync(
            $"{serverUrl}/Upgrade/Verification", request, ct);

        response.EnsureSuccessStatusCode();

        // 解析响应体
        var body = await response.Content.ReadFromJsonAsync<ServerResponse>(ct);
        // ... 映射到 UpdatePackageInfo

        return null; // 实际开发中替换为真实映射逻辑
    }

    private void WireEvents()
    {
        if (_bootstrap == null) return;

        _bootstrap.AddListenerDownloadProgressChanged += (_, e) =>
        {
            var s = e.Statistics;
            OnProgressChanged?.Invoke(this, 
                (s.ProgressPercentage, s.BytesPerSecond));
        };

        _bootstrap.AddListenerUpdateFailed += (_, e) =>
        {
            OnStatusChanged?.Invoke(this, 
                $"Failed [{e.Reason}]: {e.Message}");
        };

        _bootstrap.AddListenerUpdateCompleted += (_, e) =>
        {
            OnStatusChanged?.Invoke(this, $"Stage: {e.Stage}");
        };
    }

    // 公开事件
    public event EventHandler<(double Percentage, double Speed)>? OnProgressChanged;
    public event EventHandler<string>? OnStatusChanged;

    public void Dispose()
    {
        if (_disposed) return;
        _bootstrap?.Dispose();
        _disposed = true;
    }
}

// 结果模型
public sealed record UpdateResult
{
    public bool IsSuccess { get; init; }
    public bool IsCanceled { get; init; }
    public UpdateFailureReason FailureReason { get; init; }
    public string? Message { get; init; }

    public static UpdateResult Success() => new() { IsSuccess = true };
    public static UpdateResult NoUpdate() => new() { IsSuccess = true, Message = "No update available." };
    public static UpdateResult Canceled() => new() { IsCanceled = true, Message = "Canceled." };
    public static UpdateResult Failure(UpdateFailureReason reason, string message) =>
        new() { FailureReason = reason, Message = message };
}

// 注意：此为示例结构，实际需要替换为服务端返回的格式
public sealed record ServerResponse
{
    public int Code { get; init; }
    public List<PackageEntry>? Body { get; init; }
}

public sealed record PackageEntry
{
    public string Version { get; init; } = "";
    public string Url { get; init; } = "";
    public string Hash { get; init; } = "";
    public long Size { get; init; }
}

6. 全局配置

DI 注册方式

// 方式一：使用默认 HttpClient
services.AddGeneralUpdateMauiAndroid();

// 方式二：外部传入 HttpClient（共享连接池）
services.AddGeneralUpdateMauiAndroid(myHttpClient);

// 方式三：IHttpClientFactory 注入（通过 AddHttpClient）
services.AddHttpClient<IUpdateDownloader, HttpRangeDownloader>(client =>
{
    client.Timeout = TimeSpan.FromMinutes(10);
});
services.AddSingleton<IAndroidBootstrap, AndroidBootstrap>();
// 其他服务同理...

认证方案

MAUI 组件支持四种认证方案，可在 UpdatePackageInfo 单包粒度配置：

认证方案	AuthScheme	所需字段
HMAC-SHA256	`Hmac`	`AuthSecretKey`
Bearer Token	`Bearer`	`AuthToken`
API Key	`ApiKey`	`AuthToken`
HTTP Basic	`Basic`	`BasicUsername` + `BasicPassword`

SSL 策略

策略	类名	使用场景
系统默认（推荐）	`null`	生产环境
允许所有（仅开发）	`AllowAllSslValidationPolicy`	自签名证书开发环境
自定义	实现 `ISslValidationPolicy`	私有 CA

AndroidManifest 配置

<application>
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="${applicationId}.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/file_paths" />
    </provider>
</application>

file_paths.xml（Platforms/Android/Resources/xml/file_paths.xml）：

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <cache-path name="cache" path="update/" />
</paths>

平台差异

项目	说明
最低 API	21（Android 5.0）
安装权限	Android 8.0+ 需要 `CanRequestPackageInstalls()` 检查
FileProvider	必须通过 FileProvider 向系统安装器传递 APK 文件 URI

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

GeneralUpdate.Maui.Android

1. 组件简介

1.1 组件概述

1.2 环境与依赖

2. 组件功能列表

3. API 配置说明

3.1 配置字段（属性 Props）

3.2 实例方法

3.3 回调事件

4. 扩展示例（高阶用法）

4.1 组件可扩展能力总览

4.2 分场景示例

场景 1：DI 容器集成

场景 2：自定义 HTTP 认证

场景 3：非容器环境下的直接使用

5. 常规使用示例

5.1 快速入门示例（最简 demo）

5.2 基础参数组合示例

5.3 真实业务落地示例

6. 全局配置

DI 注册方式

认证方案

SSL 策略

AndroidManifest 配置

平台差异

相关资源

Uh oh!

FilesExpand file tree

GeneralUpdate.Maui.Android.md

Latest commit

History

GeneralUpdate.Maui.Android.md

File metadata and controls

GeneralUpdate.Maui.Android

1. 组件简介

1.1 组件概述

1.2 环境与依赖

2. 组件功能列表

3. API 配置说明

3.1 配置字段（属性 Props）

3.2 实例方法

3.3 回调事件

4. 扩展示例（高阶用法）

4.1 组件可扩展能力总览

4.2 分场景示例

场景 1：DI 容器集成

场景 2：自定义 HTTP 认证

场景 3：非容器环境下的直接使用

5. 常规使用示例

5.1 快速入门示例（最简 demo）

5.2 基础参数组合示例

5.3 真实业务落地示例

6. 全局配置

DI 注册方式

认证方案

SSL 策略

AndroidManifest 配置

平台差异

相关资源