benxu.AppPlatform.VersionCheck 3.0.3

benxu.AppPlatform.VersionCheck

跨平台 APP 版本檢查套件，支援 Android 與 iOS。

功能特色

• ✅ 自動檢查商店最新版本
• ✅ 支援強制更新與可選更新模式
• ✅ 語意化版本（Semantic Versioning）比對
• ✅ 一鍵跳轉至 Google Play Store / App Store
• ✅ 可自訂強制更新 UI

平台支援

快速開始

builder.UseAppPlatform(options =>
{
    options.UseVersionCheck(vc =>
    {
        vc.iOSBundleId = "com.yourcompany.yourapp";
        vc.AndroidPackageName = "com.yourcompany.yourapp";
        vc.ForceUpdate = true; // 強制更新
    });
});

版本檢查 (VersionCheck) 整合指南

本文件說明如何將 benxu.AppPlatform.VersionCheck 套件整合至您的 .NET MAUI Blazor Hybrid 應用程式，實現跨平台的 APP 版本檢查與強制更新功能。

1. 前置準備

在開始之前，請確保：

1. .NET 10 SDK 或更高版本
2. Visual Studio 2022 (17.10+) 或 VS Code + MAUI 擴充套件
3. 安裝 MAUI Workload：maui, android, ios

2. 安裝套件

將 benxu.AppPlatform.VersionCheck 專案引用至您的應用程式專案：

<ItemGroup>
  <ProjectReference Include="..\..\src\Infrastructure\benxu.AppPlatform.VersionCheck\benxu.AppPlatform.VersionCheck.csproj" />
</ItemGroup>

3. 初始化設定

3.1 註冊服務 (MauiProgram.cs)

在 MauiProgram.cs 中使用 Fluent API 註冊版本檢查服務：

using benxu.AppPlatform.MAUI.Bootstrap.Extensions;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    
    builder.UseAppPlatform(options =>
    {
        // 版本檢查服務
        options.UseVersionCheck(vc =>
        {
            // iOS App Store Bundle ID
            vc.iOSBundleId = "com.yourcompany.yourapp";
            
            // Google Play 套件名稱
            vc.AndroidPackageName = "com.yourcompany.yourapp";
            
            // 是否為強制更新（預設：true）
            // true = 使用者必須更新才能繼續使用
            // false = 使用者可選擇跳過
            vc.ForceUpdate = true;
            
            // 是否在 APP 啟動時自動檢查（預設：true）
            vc.CheckOnStartup = true;
            
            // 版本檢查的快取時間（秒）（預設：3600）
            vc.CacheTimeSeconds = 3600;
        });
    });

    return builder.Build();
}

3.2 加入 UI 元件

在 MainLayout.razor 或主要佈局中加入 ForceUpdateModal 元件：

@using benxu.AppPlatform.BlazorUI.Components


<ForceUpdateModal Title="發現新版本"
                  CurrentVersionLabel="目前版本"
                  LatestVersionLabel="最新版本"
                  ReleaseNotesLabel="更新內容"
                  ForceUpdateMessage="此版本包含重要更新，請立即更新後繼續使用。"
                  OptionalUpdateMessage="建議更新至最新版本以獲得更好的體驗。"
                  UpdateButtonText="立即更新"
                  SkipButtonText="稍後再說" />

3.3 多語言支援（選用）

若您的應用程式使用 benxu.AppPlatform.Localization 套件實現多語言支援，可以讓 ForceUpdateModal 的 UI 文字隨著 APP 語言設定自動切換。

步驟 1：在語言資源檔中添加翻譯鍵值

在 Resources/Localization/zh-TW.json 和 en-US.json 中添加：

{
  "update.title": "發現新版本",
  "update.currentVersion": "目前版本",
  "update.latestVersion": "最新版本",
  "update.releaseNotes": "更新內容",
  "update.forceMessage": "此版本包含重要更新，請立即更新後繼續使用。",
  "update.optionalMessage": "建議更新至最新版本以獲得更好的體驗。",
  "update.updateNow": "立即更新",
  "update.later": "稍後再說"
}

步驟 2：在 MainLayout.razor 中使用 ILocalizationService

@using benxu.AppPlatform.BlazorUI.Components.AppUpdateModal
@using benxu.AppPlatform.Core.Abstractions
@inject ILocalizationService L


<ForceUpdateModal Title="@L["update.title"]"
                  CurrentVersionLabel="@L["update.currentVersion"]"
                  LatestVersionLabel="@L["update.latestVersion"]"
                  ReleaseNotesLabel="@L["update.releaseNotes"]"
                  ForceUpdateMessage="@L["update.forceMessage"]"
                  OptionalUpdateMessage="@L["update.optionalMessage"]"
                  UpdateButtonText="@L["update.updateNow"]"
                  SkipButtonText="@L["update.later"]" />

4. 使用方式

自動檢查（預設行為）

當 CheckOnStartup = true 且 ForceUpdateModal 元件已加入佈局時，APP 啟動後會自動檢查版本並顯示更新提示。

手動檢查

若需要在特定時機手動觸發版本檢查：

@inject IVersionCheckService VersionCheckService

private async Task CheckForUpdates()
{
    var result = await VersionCheckService.CheckVersionAsync();
    
    if (result.IsSuccess && result.Data.UpdateRequired)
    {
        // 需要更新
        Console.WriteLine($"需要更新: {result.Data.CurrentVersion} → {result.Data.LatestVersion}");
        
        // 開啟商店頁面
        await VersionCheckService.OpenStoreAsync();
    }
}

取得目前版本

var currentVersion = VersionCheckService.GetCurrentVersion(); // 例如: "1.2.3"
var buildNumber = VersionCheckService.GetCurrentBuildNumber(); // 例如: 42

5. ForceUpdateModal 參數

6. 平台專屬說明

Android

• 使用 Google Play Store 網頁解析取得最新版本
• 點擊更新按鈕會開啟 market://details?id={packageName}
• 若 Play Store 未安裝，會自動轉向網頁版

iOS

• 使用 iTunes Lookup API：https://itunes.apple.com/lookup?bundleId={bundleId}
• 點擊更新按鈕會開啟 itms-apps://itunes.apple.com/app/id{appId}
• API 回應包含更新說明（releaseNotes）

7. 版本比對規則

套件使用語意化版本（Semantic Versioning）進行比對：

• 格式：Major.Minor.Patch（例如：1.2.3）
• 比對順序：Major → Minor → Patch
• 任一層級較新即視為需要更新

1.0.0 → 1.0.1  ✅ 需要更新（Patch 較新）
1.0.0 → 1.1.0  ✅ 需要更新（Minor 較新）
1.0.0 → 2.0.0  ✅ 需要更新（Major 較新）
1.2.3 → 1.2.3  ❌ 不需更新（版本相同）
1.2.3 → 1.2.2  ❌ 不需更新（本地版本較新）

8. 常見問題

Q: 如何測試版本檢查功能？

A: 在 .csproj 中將 ApplicationDisplayVersion 設為較低版本（例如 0.1），然後執行 APP。若該 APP 已上架商店，會檢測到需要更新。

<ApplicationDisplayVersion>0.1</ApplicationDisplayVersion>

Q: APP 尚未上架商店，如何測試？

A: 可暫時使用其他已上架的 bundleId 進行測試（例如 com.facebook.Messenger），確認 API 邏輯正確後再換回正式 bundleId。

Q: 為什麼 iOS 版本檢查結果不準確？

A: iTunes Lookup API 可能有 24 小時的快取延遲。此外，若 APP 有多平台版本（iOS + macOS），API 可能只回傳其中一個版本。

Q: 如何自訂更新彈窗樣式？

A: ForceUpdateModal 元件使用 CSS 變數和 scoped CSS，您可以覆寫相關樣式或複製元件到您的專案中進行修改。

9. API 參考

IVersionCheckService

VersionCheckResult