WebView2 SDK 1.0.4181-prereleaseを利用する場合、NuGetパッケージを更新するだけでは不十分です。新しいAPIを含めて完全な互換性を確保するには、Microsoft Edge 152.0.4181.0以降に含まれるWebView2 Runtimeが必要です。
特に、このSDKで追加されたDiagnostic Monitor APIはExperimental APIです。通常のEvergreen WebView2 Runtimeだけに依存せず、Edge Canaryなどのプレビューチャネルを導入し、アプリが実際に要件を満たすRuntimeを読み込んでいることまで確認してから検証を始めてください。(Microsoft Learn)
WebView2 SDK 1.0.4181-prereleaseにはRuntime 152が必要
Microsoftが2026年8月3日に公開したWebView2 SDK 1.0.4181-prereleaseでは、完全なAPI互換性を得るための最低要件として、Microsoft Edge 152.0.4181.0以降に付属するWebView2 Runtimeが指定されています。(Microsoft Learn)
今回の要件を整理すると、次のようになります。
| 確認項目 | 要件 |
|---|---|
| SDK | Microsoft.Web.WebView2 1.0.4181-prerelease |
| 最低Runtimeバージョン | 152.0.4181.0 |
| 対象 | 1.0.4181-prereleaseに含まれる新しいAPIを利用するアプリ |
| 推奨検証環境 | Microsoft Edge Canaryに含まれるWebView2 Preview Runtime |
| 利用目的 | 新機能の先行検証、互換性確認、フィードバック |
| 本番利用 | 原則としてRelease SDKとEvergreen WebView2 Runtimeを使用 |
重要なのは、Runtimeを「152.0.4181.0に固定する」必要はない点です。152.0.4181.0は最低ラインであり、それより新しい互換Runtimeであれば要件を満たします。
たとえば、次のように判断します。
- 152.0.4181.0：要件を満たす
- 152.0.4191.53：要件を満たす
- 153以降のPreview Runtime：通常は要件を満たすが、実際のAPI動作も検証する
- 151.0.4129.50：要件を満たさない
「WebView2が起動する要件」と「新APIが動く要件」は異なる
WebView2自体を生成するための基本的な最低Runtimeバージョンは86.0.616.0です。しかし、これはWebView2を読み込める最低条件であり、SDK 1.0.4181-prereleaseの新APIが利用できることを意味しません。(Microsoft Learn)
そのため、次のような状態が起こり得ます。
- WebView2の画面は正常に表示される
- 既存のナビゲーションやJavaScript実行は動作する
- 1.0.4181-prereleaseで追加されたAPIだけが失敗する
「画面が表示されたからRuntime要件を満たしている」と判断するのは危険です。新しいAPIを呼び出す前に、実際に使用されるRuntimeのバージョンを確認する必要があります。
SDKとRuntimeは役割が異なる
WebView2 SDKは、アプリをビルドするためのAPI定義やライブラリを提供します。一方、APIの実際の処理は、端末上のWebView2 RuntimeやMicrosoft Edgeプレビューチャネル側に実装されています。
このため、SDKだけを更新すると、次の状態になります。
- コンパイル時には新しいクラスやメソッドが認識される
- ビルドも正常に完了する
- 実行時に古いRuntimeが読み込まれる
- 新APIに対応するインターフェイスが見つからず失敗する
Microsoftの説明では、SDKのビルド番号よりRuntimeのビルド番号が古い場合、新しいAPIの実装を利用できません。SDK 1.0.4181-prereleaseとRuntime 152.0.4181.0では、対応関係を示すビルド番号として「4181」が使われています。(Microsoft Learn)
1.0.4181-prereleaseで追加されたDiagnostic Monitor API
WebView2 SDK 1.0.4181-prereleaseでは、Experimental APIとしてDiagnostic Monitor APIが追加されました。
Diagnostic Monitorは、WebView2で発生する診断情報をホストアプリ側から収集するための監視用APIです。複数のWebView、プロファイル、環境から発生した情報を、DiagnosticReceivedイベントを通じて受け取れます。(Microsoft Learn)
主な構成要素は次のとおりです。
| API | 用途 |
|---|---|
CreateDiagnosticMonitor | 診断モニターを作成する |
SetDiagnosticFilter | 取得する診断イベントを絞り込む |
RemoveDiagnosticFilter | 設定済みのフィルターを削除する |
DiagnosticReceived | 診断情報を受信する |
DetailsAsJson | 診断内容をJSON形式で取得する |
Close | 監視を終了してフィルターをクリアする |
初期段階では、NetworkRequestなどのカテゴリを指定して、ネットワーク関連の診断情報を収集できます。SetDiagnosticFilterに空のJSONオブジェクトである{}を指定すると、そのカテゴリのすべてのイベントを受信します。条件を含むJSONを指定すれば、HTTPメソッドやエラーコードなどで対象を絞り込めます。(Microsoft Learn)
ただし、このAPIは観測専用です。受信したイベントを途中で変更したり、ネットワーク処理を停止したり、処理を遅延させたりする用途には使えません。
また、Diagnostic Monitor APIはExperimental APIであり、今後のSDKやRuntimeで名前、引数、動作が変更される可能性があります。本番機能として組み込むより、障害解析やテレメトリ設計の事前検証に利用するのが適切です。
SDK 1.0.4181-prereleaseを検証する手順
NuGetパッケージを1.0.4181-prereleaseへ更新する
.NETプロジェクトでは、Microsoft.Web.WebView2パッケージを1.0.4181-prereleaseへ更新します。
.NET CLIを使用する場合は、プロジェクトのフォルダーで次のコマンドを実行します。
dotnet add package Microsoft.Web.WebView2 --version 1.0.4181-prereleaseVisual Studioから更新する場合は、次の手順です。
- ソリューションエクスプローラーで対象プロジェクトを右クリックする
- 「NuGetパッケージの管理」を開く
- 「プレリリースを含める」を有効にする
Microsoft.Web.WebView2を検索する1.0.4181-prereleaseを選択してインストールする- ソリューションをクリーンして再ビルドする
WebView2 SDKを更新した後は、古い生成物が残らないように再ビルドしてください。Microsoftも、SDKのNuGetパッケージを更新した後にWebView2アプリを再コンパイルすることを推奨しています。(Microsoft Learn)
Microsoft Edgeのプレビューチャネルを導入する
Experimental APIを利用する場合は、Microsoft Edge Beta、Dev、Canaryのいずれかに含まれるWebView2 Preview Runtimeを使用します。
Microsoftは、最も新しいAPI実装を利用できる可能性が高いCanaryチャネルを推奨しています。Prerelease SDKは、公開直後にはCanaryのみで動作し、時間がたつとDevやBetaでも利用できるようになる場合があります。(Microsoft Learn)
検証端末では、少なくとも次の点を確認してください。
- Microsoft Edge Canaryなどのプレビューチャネルがインストールされている
- プレビューチャネルのバージョンが152.0.4181.0以上である
- 組織の更新ポリシーによって更新が停止されていない
- アプリがStable Runtimeではなく、意図したプレビューチャネルを読み込んでいる
Stable Runtimeが選ばれないようにチャネルを指定する
Microsoft Edge Canaryをインストールしただけでは、アプリがCanaryを使用するとは限りません。
WebView2の既定の検索順序は、安定性の高いチャネルから低いチャネルへ進みます。
WebView2 Runtime（Stable）
→ Edge Beta
→ Edge Dev
→ Edge Canary端末にStableのEvergreen WebView2 Runtimeが入っている場合、既定設定ではStable Runtimeが先に選ばれる可能性があります。その結果、Canaryをインストール済みでもExperimental APIを利用できないことがあります。(Microsoft Learn)
.NETでは、WebView2を初期化する前に使用チャネルを指定できます。
using Microsoft.Web.WebView2.Core;
var options = new CoreWebView2EnvironmentOptions
{
ReleaseChannels = CoreWebView2ReleaseChannels.Canary,
ChannelSearchKind = CoreWebView2ChannelSearchKind.LeastStable
};
var environment = await CoreWebView2Environment.CreateAsync(
null,
null,
options);
await webView2.EnsureCoreWebView2Async(environment);ReleaseChannelsをCanaryだけに限定すると、Stable、Beta、Devへの意図しないフォールバックを防げます。一方、Canaryがインストールされていない場合は、環境の作成が失敗します。
Canaryを優先しつつDevやBetaも許可する場合は、次のように複数のチャネルを指定できます。
var options = new CoreWebView2EnvironmentOptions
{
ReleaseChannels =
CoreWebView2ReleaseChannels.Canary |
CoreWebView2ReleaseChannels.Dev |
CoreWebView2ReleaseChannels.Beta,
ChannelSearchKind = CoreWebView2ChannelSearchKind.LeastStable
};再現性の高い検証を行う場合は、複数チャネルへのフォールバックを許可せず、Canaryなど一つのチャネルに限定する方が原因を切り分けやすくなります。
なお、チャネル指定はWebView2コントロールを初期化する前に行う必要があります。Sourceの設定やEnsureCoreWebView2Asyncの実行後に変更しても、すでに作成された環境には反映されません。(Microsoft Learn)
Runtimeのバージョンをコードで確認する
Runtime要件は、コントロールパネルやインストール済みアプリの一覧だけで判断しない方が安全です。
端末に複数のRuntimeやEdgeチャネルが存在する場合、重要なのは「インストールされているバージョン」ではなく「アプリが選択するバージョン」です。
.NETでは、GetAvailableBrowserVersionStringを使って、指定条件で検出されるRuntimeまたはEdgeチャネルのバージョンを取得できます。Runtimeが見つからない場合は、WebView2RuntimeNotFoundExceptionが発生します。(Microsoft Learn)
次の例では、Canaryを対象として152.0.4181.0以上であることを確認しています。
using Microsoft.Web.WebView2.Core;
const string MinimumRuntimeVersion = "152.0.4181.0";
var options = new CoreWebView2EnvironmentOptions
{
ReleaseChannels = CoreWebView2ReleaseChannels.Canary,
ChannelSearchKind = CoreWebView2ChannelSearchKind.LeastStable
};
string detectedVersion;
try
{
detectedVersion =
CoreWebView2Environment.GetAvailableBrowserVersionString(
null,
options);
}
catch (WebView2RuntimeNotFoundException ex)
{
throw new InvalidOperationException(
"WebView2 Preview Runtimeが見つかりません。Edge Canaryのインストール状態を確認してください。",
ex);
}
if (CoreWebView2Environment.CompareBrowserVersions(
detectedVersion,
MinimumRuntimeVersion) < 0)
{
throw new NotSupportedException(
$"WebView2 Runtime {MinimumRuntimeVersion} 以上が必要です。" +
$"検出されたバージョン: {detectedVersion}");
}
var environment = await CoreWebView2Environment.CreateAsync(
null,
null,
options);
Console.WriteLine(
$"実際に使用するRuntime: {environment.BrowserVersionString}");
await webView2.EnsureCoreWebView2Async(environment);バージョン文字列を単純比較しない
次のような文字列比較は避けてください。
if (detectedVersion.CompareTo("152.0.4181.0") >= 0)
{
// この判定方法は適切ではない
}通常の文字列比較では、各数値をバージョン要素として正しく比較できません。また、プレビューチャネルのバージョン情報にはチャネル名が含まれる場合があります。
WebView2のバージョン比較には、CoreWebView2Environment.CompareBrowserVersionsを使用します。このメソッドは、1番目のバージョンが古い場合は負の値、同じ場合は0、新しい場合は正の値を返します。(Microsoft Learn)
最終判定にはBrowserVersionStringを使う
GetAvailableBrowserVersionStringは、初期化前の事前確認に利用できます。ただし、レジストリ、環境変数、グループポリシー、BrowserExecutableFolderなどの上書き設定によって、想定と異なるチャネルが選ばれる可能性があります。
環境作成後は、次のプロパティも記録してください。
string actualVersion = environment.BrowserVersionString;テストログには、少なくとも次の情報を出力しておくと原因を追いやすくなります。
SDK: 1.0.4181-prerelease
要求Runtime: 152.0.4181.0以上
検出Runtime: 152.0.xxxx.xx canary
実際のRuntime: 152.0.xxxx.xx canary
OS: Windows 11
アプリビルド: 2026.08.03-test01Runtimeを更新した後はアプリを再起動する
Evergreen WebView2 RuntimeやMicrosoft Edgeのチャネルが更新されても、起動中のアプリが直ちに新しいRuntimeへ切り替わるとは限りません。
WebView2環境を作成済みのプロセスは、終了するまで以前のRuntimeを使い続ける場合があります。新しいRuntimeを利用するには、WebView2環境への参照をすべて解放するか、アプリを再起動する必要があります。(Microsoft Learn)
開発端末では、次のプロセスが残っていないか確認します。
- デバッグ中のアプリ
- Visual Studioから起動したテストプロセス
- 常駐型のバックグラウンドプロセス
- WebView2を利用する補助ツール
- 自動テストエージェント
Runtime更新後も古いバージョンが表示される場合は、アプリを閉じるだけでなく、関連プロセスが完全に終了していることをタスクマネージャーで確認してください。
よくある失敗と対処方法
| 症状 | 主な原因 | 対処方法 |
|---|---|---|
| ビルドは成功するが新APIの呼び出しで失敗する | SDKだけ更新し、Runtimeが古い | 実際に選択されたRuntimeを確認し、152.0.4181.0以上へ更新する |
| Canaryを入れたのにExperimental APIが動かない | Stable Runtimeが先に選択されている | ReleaseChannelsとChannelSearchKindを初期化前に指定する |
| 開発PCでは動くがテストPCでは動かない | テストPCの更新停止、Preview Runtime未導入 | テストPCでもバージョンとチャネルをコードから記録する |
| Runtime更新後も旧バージョンが表示される | アプリが古いRuntimeを読み込んだまま動作している | 関連プロセスを終了して再起動する |
| Runtimeが見つからない | 指定したCanaryなどが未導入 | プレビューチャネルのインストール状態を確認する |
| バージョン判定が不安定になる | 通常の文字列比較を使っている | CompareBrowserVersionsを使う |
| 設定したチャネルと別のRuntimeが使われる | 環境変数やポリシーによる上書き | BrowserVersionStringと端末ポリシーを確認する |
| 固定版Runtimeを配布している環境だけ失敗する | アプリに同梱したRuntimeが古い | 配布パッケージ内のRuntimeも更新する |
TargetCompatibleBrowserVersionだけでは導入は完了しない
CoreWebView2EnvironmentOptionsには、必要な互換Runtimeバージョンを指定するTargetCompatibleBrowserVersionがあります。
var options = new CoreWebView2EnvironmentOptions
{
TargetCompatibleBrowserVersion = "152.0.4181.0"
};ただし、このプロパティを設定しても、端末に存在しないRuntimeが自動的にインストールされるわけではありません。また、実際に選択されるRuntimeは指定値と完全に同一になるとは限らず、互換性を満たす別のバージョンが使用される場合があります。
Microsoftのドキュメントでも、実際に使用されたバージョンはBrowserVersionStringで確認するよう案内されています。(Microsoft Learn)
そのため、次の三つは別々に実施する必要があります。
- 必要なRuntimeまたはEdgeプレビューチャネルを端末へ導入する
- WebView2が使用するチャネルを指定する
- 実際に読み込まれたバージョンを確認する
管理されたPCやオフライン環境での注意点
企業や自治体などの管理端末では、WebView2 RuntimeやMicrosoft Edgeの更新がポリシーで制御されている場合があります。
Evergreen Runtimeは通常、自動的に更新されます。しかし、管理者が更新を抑止している端末や、長期間オフラインの端末では、SDKより古いRuntimeが残ることがあります。Microsoftも、管理者による更新停止やオフライン状態を想定し、新しいAPIを利用する際は機能の存在確認を行うよう推奨しています。(Microsoft Learn)
検証環境を準備するときは、次の項目を管理者へ確認してください。
- Edge Canary、Dev、Betaのインストールが許可されているか
- プレビューチャネルの自動更新が許可されているか
- WebView2のチャネル選択ポリシーが設定されていないか
- 実行ファイル単位のWebView2ポリシーが存在しないか
- プロキシやファイアウォールが更新通信を妨げていないか
- テスト端末のスナップショットや復元処理で古いRuntimeへ戻っていないか
オフライン端末で検証する場合は、通常のEvergreen Standalone Installerを用意するだけでは、Experimental APIの検証環境として不十分な可能性があります。Microsoftが案内するPreview Runtimeまたはプレビューチャネルのセルフホスト手順を基に、検証専用の環境を分離して構築するのが安全です。
アプリ側にはRuntime不足時の処理を入れる
SDK 1.0.4181-prereleaseを使う場合でも、Runtime要件を満たさない端末でアプリ全体を強制終了させる必要があるとは限りません。
Diagnostic Monitorが補助的な診断機能であれば、Runtimeが古い場合はその機能だけを無効化する設計が現実的です。
bool supportsRequiredRuntime =
CoreWebView2Environment.CompareBrowserVersions(
detectedVersion,
"152.0.4181.0") >= 0;
if (!supportsRequiredRuntime)
{
DisableDiagnosticMonitorFeature();
ShowRuntimeUpdateMessage();
}実務では、次のように機能を分類しておくと判断しやすくなります。
| 機能の位置付け | Runtime不足時の対応 |
|---|---|
| アプリの中核機能 | 起動を停止し、必要バージョンと更新方法を表示する |
| 診断・ログ収集機能 | 対象機能だけ無効化してアプリは継続する |
| 管理者向け機能 | 管理画面に警告を表示し、一般ユーザーへの影響を抑える |
| 試験導入中の機能 | 機能フラグで無効化できるようにする |
「新APIが存在するはず」と仮定して直接呼び出すのではなく、バージョン確認や例外処理を組み込んでください。.NETやWinUI、WinRTでは、新しいAPIの呼び出しをtry-catchで囲み、No such interface supportedに相当する例外を検出する方法も案内されています。(Microsoft Learn)
Prerelease SDKを本番環境へ投入するべきか
WebView2 SDK 1.0.4181-prereleaseは、新しいAPIを先行検証するためのSDKです。Experimental APIは将来のRuntime更新で変更または削除される可能性があり、前方互換性も保証されていません。
Microsoftは、本番アプリのビルドにPrerelease SDKを使用することを避け、Release SDKとEvergreen WebView2 Runtimeの組み合わせを使用するよう案内しています。(Microsoft Learn)
利用判断の目安は次のとおりです。
| 利用場面 | 推奨構成 |
|---|---|
| 新APIの技術調査 | 1.0.4181-prerelease＋Edge Canary |
| 開発チーム内の検証 | Prerelease SDK＋バージョンを確認したPreview Runtime |
| 自動テスト | 使用チャネルとRuntimeバージョンを固定・記録する |
| 限定的な社内パイロット | 機能フラグ、例外処理、無効化手段を用意する |
| 一般ユーザー向け本番配布 | APIがRelease SDKへ昇格するまで待つ |
| 安定性を優先する業務アプリ | Release SDK＋Evergreen Runtime |
Experimental APIをどうしても先行導入する場合は、対象端末を限定し、Runtimeの更新タイミングを管理できる環境で運用してください。
検証前に確認するチェックリスト
WebView2 SDK 1.0.4181-prereleaseの検証を始める前に、次の項目を確認します。
- プロジェクトが
Microsoft.Web.WebView2の1.0.4181-prereleaseを参照している - パッケージ更新後にクリーンと再ビルドを実施した
- Edge Canaryなどのプレビューチャネルを導入した
- プレビューチャネルが152.0.4181.0以上である
- WebView2初期化前に使用チャネルを指定した
GetAvailableBrowserVersionStringで事前確認したCompareBrowserVersionsで最低バージョンを判定したBrowserVersionStringで実際の使用バージョンを記録した- Runtime更新後にアプリと関連プロセスを再起動した
- Runtime不足時に新機能だけを無効化できる
- テスト端末でも同じ確認ログを取得できる
- 本番コードと検証コードを機能フラグなどで分離した
WebView2 SDK 1.0.4181-prereleaseを正しく検証するには、SDKの更新、Runtime 152.0.4181.0以上の導入、プレビューチャネルの選択、実際のRuntimeバージョン確認までを一つの作業として扱う必要があります。
まず検証端末へEdge Canaryを導入し、アプリがCanaryを選択するよう初期化条件を設定してください。その後、BrowserVersionStringで152.0.4181.0以上が使われていることを確認してから、Diagnostic Monitorなどの新APIを試すのが確実です。
コメント