ASP.NET Core アプリをデバッグする

この記事では、Blazor アプリをデバッグする方法について説明します。これには、ブラウザー開発者ツールや統合開発環境 (IDE) を使用した Blazor WebAssembly アプリのデバッグが含まれます。

前提条件

このセクションでは、デバッグの前提条件について説明します。

ブラウザーの前提条件

ファイアウォールまたはプロキシでデバッグ プロキシ (NodeJS プロセス) との通信がブロックされていないことを確認します。 詳細については、「ファイアウォールの構成」セクションをご覧ください。

IDE の前提条件

Visual Studio または Visual Studio Code の最新バージョンが必要です。

Visual Studio Code の前提条件

Visual Studio Code を使用する場合は、Visual Studio Code 用の C# 開発キット (VS Code での C# スタート ガイド) が必要です。 Visual Studio Code 拡張機能マーケットプレースで、拡張機能の一覧を "c# dev kit" というフィルターで絞り込んで、この拡張機能を見つけてください。

C# 開発キットをインストールすると、次の追加の拡張機能が自動的にインストールされます。

• .NET インストール ツール
• C#
• C# 開発キット用 IntelliCode

警告やエラーが発生した場合は、イシューを提起し (microsoft/vscode-dotnettools GitHub リポジトリ)、問題について説明してください。

アプリ構成の前提条件

このサブセクションのガイダンスは、クライアント側デバッグに適用されます。

スタートアップ プロジェクトの Properties/launchSettings.json ファイルを開きます。 ファイルの profiles ノードの各起動プロファイルに、次の inspectUri プロパティがあることを確認します。 次のプロパティが存在しない場合は、各プロファイルに追加します。

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

inspectUri プロパティ:

• アプリが Blazor アプリであることを IDE で検出できるようにします。
• スクリプト デバッグ インフラストラクチャに対して、Blazor のデバッグ プロキシを使用してブラウザーに接続するように指示します。

起動したブラウザー (browserInspectUri) の WebSocket プロトコル (wsProtocol)、ホスト (url.hostname)、ポート (url.port)、およびインスペクター URI のプレースホルダー値は、フレームワークによって提供されます。

パッケージ

スタンドアロンの Blazor WebAssembly: Microsoft.AspNetCore.Components.WebAssembly.DevServer: Blazor アプリのビルド時に使う開発サーバー。 内部で UseWebAssemblyDebugging を呼び出して、Chromium 開発者ツール内で Blazor WebAssembly アプリをデバッグするためのミドルウェアを追加します。

IDE で Blazor WebAssembly アプリをデバッグする

<DebuggerSupport>true</DebuggerSupport>
<CopyOutputSymbolsToPublishDirectory>true</CopyOutputSymbolsToPublishDirectory>

既存の Visual Studio Code デバッグ セッションにアタッチする

実行中の Blazor アプリにアタッチするには、.vscode/launch.json ファイルを開き、{URL} プレースホルダーをアプリが実行されている URL に置き換えます。

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Visual Studio Code の起動オプション

blazorwasm のデバッグの種類では、次のテーブルに記載の起動構成オプションがサポートされています (.vscode/launch.json)。

Google Chrome または Microsoft Edge で Blazor WebAssembly をデバッグする

このセクションのガイダンスは、次における Blazor WebAssembly アプリのデバッグに適用されます。

• Windows または macOS で実行されている Google Chrome。
• *Windows で実行されている Microsoft Edge。

1. dotnet watch (または dotnet run) を使用して、コマンド シェルでアプリを実行します。

2. ブラウザーを起動し、アプリの URL に移動します。

3. 次を押してリモート デバッグを開始します。

   • Windows の場合、Shift+Alt+d。
   • macOS の場合、Shift+⌘+d。

   ブラウザーはリモート デバッグが有効で実行されている必要があります。これは既定ではありません。 リモート デバッグが無効になっている場合、"デバッグ可能なブラウザー タブが見つからない" というエラー ページと、デバッグ ポートを開いた状態でブラウザーを起動する手順がレンダリングされます。 お使いのブラウザーの手順に従います。

   手順に従ってリモート デバッグを有効にすると、アプリが新しいブラウザー ウィンドウで開きます。 新しいブラウザー ウィンドウで、ホット キーの組み合わせを押してリモート デバッグを開始します。

   • Windows の場合、Shift+Alt+d。
   • macOS の場合、Shift+⌘+d。

   新しいウィンドウで開発者ツールのブラウザー タブが開き、アプリのゴースト画像が表示されます。

   Note

   リモート デバッグを有効にして新しいブラウザー タブを開く手順に従った場合は、元のブラウザー ウィンドウを閉じ、2 番目のウィンドウは開いたままにして、1 つ目のタブでアプリを実行しながら 2 つ目のタブでデバッガーを実行できます。

4. 少しすると、[ソース] タブに、アプリの .NET アセンブリとページの一覧が表示されます。

5. file:// ノードを開きます。 コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) の中で設定したブレークポイントは、そのコードがアプリのブラウザー タブ (リモート デバッグの開始後に開いた最初のタブ) で実行されるときにヒットします。 ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、デバッグ タブでコードの実行を通常どおりに再開 (F8) します。

Chromium ベースのブラウザーでのデバッグの場合、Blazor は Chrome DevTools プロトコルを実装し、.NET 固有の情報によってプロトコルを拡張するデバッグ プロキシを備えています。 デバッグ用のキーボード ショートカットが押されると、Blazor はプロキシで Chrome DevTools を指し示します。 プロキシは、デバッグしようとしているブラウザー ウィンドウに接続します (そのためリモート デバッグを有効にする必要があります)。

ハンドルされない例外の発生時に中断する

Blazor では開発者コードによってハンドルされない例外をキャッチするため、デバッガーは、ハンドルされない例外の発生時には中断しません。

ハンドルされない例外の発生時に中断するには:

• Visual Studio でデバッガーの例外設定を開きます ([デバッグ] > [Windows] > [例外設定])。
• 次の JavaScript 例外設定を指定します。
  • すべての例外
  • キャッチされない例外

ブラウザー ソース マップ

ブラウザー ソース マップを使用すると、ブラウザーのコンパイルされたファイルを元のソース ファイルにマップし直すことができ、これはクライアント側のデバッグによく使用されます。 ただし Blazor では現在、C# は JavaScript/WASM に直接マップされません。 その代わり、Blazor はブラウザー内で中間言語の解釈を行うため、ソース マップは関係がありません。

ファイアウォールの構成

ファイアウォールでデバッグ プロキシとの通信がブロックされている場合は、ブラウザーと NodeJS プロセス間の通信を許可するファイアウォールの例外規則を作成します。

Windows ファイアウォールの構成ガイダンスについては、受信プログラムまたはサービス規則の作成に関する記事をご覧ください。 詳細については、Windows ファイアウォールのドキュメント セットで高度なセキュリティを備えた Windows Defender ファイアウォールに関連する記事をご覧ください。

トラブルシューティング

エラーが発生している場合は、次のヒントが役立つことがあります。

• ブレークポイントの削除:
  • Google Chrome: [デバッガー] タブで、ブラウザーで開発者ツールを開きます。 コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。
  • Microsoft Edge: [アプリケーション] タブで、[ローカル ストレージ] を開きます。 サイトを右クリックして [消去] を選びます。
• ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。 詳細については、「ASP.NET Core で HTTPS を適用する」を参照してください。
• Visual Studio では、[ツール]>[オプション]>[デバッグ]>[全般] で [ASP.NET (Chrome と Edge) の JavaScript デバッグを有効にする] オプションをオンにする必要があります。 これは、Visual Studio の既定の設定です。 デバッグが機能していない場合は、オプションがオンになっていることを確認します。
• ご利用の環境で HTTP プロキシを使用している場合は、プロキシ バイパス設定に localhost が含まれていることを確認してください。 これを行うには、次のいずれかに NO_PROXY 環境変数を設定します。
  • プロジェクトの launchSettings.json ファイル。
  • すべてのアプリに適用する場合は、ユーザーまたはシステム環境変数レベルで。 環境変数を使用する場合は、Visual Studio を再起動して変更を有効にしてください。
• ファイアウォールまたはプロキシでデバッグ プロキシ (NodeJS プロセス) との通信がブロックされていないことを確認します。 詳細については、「ファイアウォールの構成」セクションをご覧ください。

OnInitialized{Async} 内のブレークポイントにヒットしない

Blazor フレームワークのデバッグ プロキシは、アプリの起動時にすぐには起動しません。そのため、OnInitialized{Async} ライフサイクル メソッド内のブレークポイントにヒットしない可能性があります。 デバッグ プロキシが起動してブレークポイントにヒットするまでの時間を確保するために、メソッド本体の開始に対して遅延を追加することをお勧めします。 if コンパイラ ディレクティブに基づいて遅延を含めると、アプリのリリース ビルドに対しては遅延が存在しないようにすることができます。

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Visual Studio (Windows) のタイムアウト

Visual Studio で、タイムアウトに達したことを示すデバッグ アダプターの起動失敗の例外がスローされた場合、レジストリ設定でタイムアウトを調整できます。

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

上記のコマンドの {TIMEOUT} プレースホルダーはミリ秒単位です。 たとえば、1 分は 60000 として割り当てられます。