VelopackUpdateDialog.Avalonia 1.0.6

VelopackUpdateDialog.Avalonia

Avalonia 12 で動く Velopack 自動更新ダイアログ の再利用可能パッケージ。

Window / UserControl / ViewModel の 3 段提供で、ホストアプリの設計に合わせて柔軟に組み込める。

インストール

dotnet add package VelopackUpdateDialog.Avalonia

依存: Avalonia 12.0.4+, CommunityToolkit.Mvvm 8.4.2+, Velopack 1.0.1+, TFM net10.0。

📦 PackageId と namespace について: NuGet パッケージ名は VelopackUpdateDialog.Avalonia ですが、C# namespace は VelopackUpdateDialog（.Avalonia 接尾辞なし）です。将来の WPF/WinForms 派生パッケージとの namespace 共有を見越した設計です。

最短の使い方

using Velopack;
using Velopack.Sources;
using VelopackUpdateDialog;

var mgr = new UpdateManager(new GithubSource("https://github.com/owner/repo", string.Empty, false));
await UpdateDialogWindow.ShowAsync(parentWindow, mgr);

オプション指定

// 例: MyJapaneseStrings は IUpdateDialogStrings を実装するユーザー定義クラス。
//     最小実装は samples/DemoApp/MainWindow.axaml.cs の JapaneseStrings を参照。

var options = new UpdateDialogOptions
{
    // 表示文字列を差し替え（日本語 etc.）
    Strings = new MyJapaneseStrings(),

    // 大昔の SelfUpdate 風: ウィンドウ固定サイズ（デフォルト）
    ResizeMode = WindowResizeMode.Fixed,

    // 可変ウィンドウにする場合
    // ResizeMode = WindowResizeMode.Resizable,
    // InitialSize = new Size(600, 240),
    // MinSize = new Size(400, 160),

    ChromeMode = WindowChromeMode.Custom,  // OS フレームを使うなら System
    AccentBrush = Brushes.DodgerBlue,
    AllowIgnoreVersion = true,
    AllowCloseDuringDownload = true,
    SuppressUpToDateOnAutoCheck = true,

    // 自動チェック時はこのタグの更新を無視 (ホスト側で保存した IgnoreUpdateTag を渡す)
    IgnoredTagName = Preferences.IgnoreUpdateTag,
};

// 「このバージョンを無視」を押された時の永続化処理
options.VersionIgnored += tag => Preferences.IgnoreUpdateTag = tag;

// エラーが起きた時のロギング
options.ErrorOccurred += ex => Logger.LogException("更新失敗", ex);

var result = await UpdateDialogWindow.ShowAsync(parentWindow, mgr, options, manualCheck: true);

switch (result.Outcome)
{
    case UpdateOutcome.Updated:    /* 再起動指示済み */ break;
    case UpdateOutcome.UpToDate:   /* 最新版 */ break;
    case UpdateOutcome.Ignored:    /* ユーザーが無視を選択 */ break;
    case UpdateOutcome.Cancelled:  /* ダウンロード中断 */ break;
    case UpdateOutcome.Failed:     /* result.Error 参照 */ break;
    case UpdateOutcome.Closed:     /* 単純に閉じられた */ break;
}

レイヤー別の提供

1. UpdateDialogWindow — そのまま ShowAsync

完成形ウィンドウ。タイトルバー込み。

2. UpdateDialogView : UserControl — 任意 Window に貼り付け

<Window xmlns:upd="using:VelopackUpdateDialog">
    <upd:UpdateDialogView DataContext="{Binding UpdateVm}"/>
</Window>

var vm = new UpdateDialogViewModel(updateManager, options);
MyWindow.DataContext = vm;
await vm.CheckAsync(manualCheck: true);

3. UpdateDialogViewModel — 完全自前 UI

状態機械と Velopack 呼び出しロジックだけを再利用し、UI は完全自前で組む場合。

var vm = new UpdateDialogViewModel(updateManager);
vm.PropertyChanged += (_, e) =>
{
    if (e.PropertyName == nameof(vm.State))
    {
        // 自前の UI を更新
    }
};
await vm.CheckAsync(manualCheck: true);

カスタマイズ拡張点

動作

ダウンロード完了後、Velopack の ApplyUpdatesAndRestart を自動呼び出し。

manualCheck の挙動差

これにより自動チェックは「無関係な時は一切ポップアップを出さない」挙動になり、起動時のサイレントチェックに適する。

事前条件

• ホストアプリは Velopack でパッケージ化 (vpk pack) されている必要がある。UpdateManager.IsInstalled が false の場合 (= vpk pack を経ていない開発実行など)、本ライブラリは常に UpdateOutcome.UpToDate を返す
• ホストアプリの Program.Main 冒頭で VelopackApp.Build().Run() を呼ぶこと (Velopack 公式の事前要件)
• TFM net10.0 以上

ロギング

本ライブラリは SuperLightLogger を内部で使用しており、状態遷移と失敗時のスタックトレースを Microsoft.Extensions.Logging 抽象で出力する。ホストアプリで以下を設定すると拾える（コンソール出力には Microsoft.Extensions.Logging.Console パッケージが必要）:

using Microsoft.Extensions.Logging;

SuperLightLogger.LogManager.Configure(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

設定しなくても Options.ErrorOccurred イベントで失敗時の Exception が 1 回通知されるが、運用環境ではロガー設定を推奨する。

⚠️ 起動時の自動チェックを fire-and-forget (_ = ShowAsync(...)) で呼ぶ場合、戻り値の UpdateDialogResult を見ないため、失敗を観測する手段が Options.ErrorOccurred の購読かロガー設定だけになる。プロキシ遮断・TLS 失敗などを静かに見逃さないよう、自動チェック時は最低でも ErrorOccurred を購読することを推奨する。

Troubleshooting

Security Considerations

• コード署名: Velopack の vpk pack --signParams (Windows: SignTool) / --signEntitlements (macOS: codesign) で配布パッケージに必ず署名を施すこと。未署名運用は、GitHub Release への push 権限を握った攻撃者が任意コード実行を仕込める経路になる
• GitHub Repository 設定: Release への push 権限は branch protection + required reviews で絞ること
• アクセストークン: 平文設定ファイルへの保存は避け、Windows Credential Manager / macOS Keychain / DPAPI などで保護する。accessToken は GithubSource 経由で Authorization ヘッダに送信される
• エラーログ: Options.ErrorOccurred で受け取った Exception を外部テレメトリ (Sentry / Application Insights 等) に送る場合、本ライブラリは生のメッセージを sanitize しない。ホスト側でロガー設定時に PII / token を redact すること

詳細は Velopack 公式ドキュメント も参照。

License

MIT