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

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

Blazor Web アプリのデバッグは Visual Studio または Visual Studio Code で行うことができます。

Blazor WebAssembly アプリは、次のようにデバッグできます。

• Visual Studio または Visual Studio Code で。
• Chromium ベースのブラウザー (Microsoft Edge、Google Chrome、Firefox など) でブラウザー開発者ツールを使用して。

Blazor WebAssembly のデバッグで使用できるシナリオは、次のとおりです。

• ブレークポイントの設定と削除を行う。
• IDE でデバッグ サポートを使用してアプリを実行する。
• コードを 1 ステップずつ実行する。
• IDE でキーボード ショートカットを使用してコード実行を再開する。
• [ローカル] ウィンドウで、ローカル変数の値を観察する。
• JavaScript と .NET の間の呼び出しチェーンなど、呼び出し履歴を確認する。
• Visual Studio の基本設定で構成したデバッグのシンボル サーバーを使います。

サポートされないシナリオは、次のとおりです。

• ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL) や Visual Studio Codespaces) でデバッグします。
• Visual Studio または Visual Studio Code からの Firefox でのデバッグ。

前提条件

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

ブラウザーの前提条件

次のブラウザーの最新バージョン:

• Google Chrome
• Microsoft Edge
• Firefox (ブラウザー開発者ツールのみ)

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

Note

現在、macOS での Apple Safari はサポートされていません。

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 Web Apps: Microsoft.AspNetCore.Components.WebAssembly.Server: ブラウザー デバッグ ホストを共有するアセンブリの内部パッケージ (Microsoft.NETCore.BrowserDebugHost.Transport) を参照します。

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

Note

.NET アプリへのパッケージの追加に関するガイダンスについては、「パッケージ利用のワークフロー」 (NuGet ドキュメント) の "パッケージのインストールと管理" に関する記事を参照してください。 NuGet.org で正しいパッケージ バージョンを確認します。

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

Visual Studio

このセクションの例では、対話型レンダリング モードが "自動" (サーバーと WebAssembly) で、インタラクティビティの場所が "コンポーネントごと" の Blazor Web アプリを作成済みであることを前提としています。

1. アプリを開く
2. クライアント プロジェクト (.Client) の Counter コンポーネント (Pages/Counter.razor) で、currentCount++; の行にブレークポイントを設定します。
3. F5 キーを押して、デバッガーでアプリを実行します。
4. ブラウザーで、Counter (/counter) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。
5. Visual Studio の [ローカル] ウィンドウで、currentCount フィールドの値を調べます。
6. F5 キーを押して、実行を続行します。

ブレークポイントはサーバー プロジェクト内でも、静的レンダリングされる、および対話型レンダリングされるサーバー側コンポーネントの中でヒットすることができます。

1. デバッガーを停止します。

2. 次のコンポーネントをサーバー アプリに追加します。 このコンポーネントによって "対話型サーバー" レンダリング モード (InteractiveServer) が適用されます。

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Counter2 コンポーネントで currentCount++; の行にブレークポイントを設定します。

4. F5 キーを押して、デバッガーでアプリを実行します。

5. ブラウザーで、Counter2 (/counter-2) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。

6. F5 キーを押して、実行を続行します。

デバッグ プロキシが実行状態になる前のアプリの起動中には、ブレークポイントで停止することはありません。 これには、Program ファイルのブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。

Visual Studio Code

このセクションの例では、レンダリング モードが対話型の自動 (サーバーと WebAssembly) で、インタラクティビティの場所がコンポーネントごとである Blazor Web アプリを作成済みであることを前提としています。

1. Visual Studio Code でアプリを開くには、ソリューション フォルダー (サーバーと .Client プロジェクトのフォルダーを含むフォルダー) を開きます。
2. クライアント プロジェクト (.Client) の Counter コンポーネント (Pages/Counter.razor) で、currentCount++; の行にブレークポイントを設定します。
3. [実行とデバッグ] ウィンドウを開き、[実行とデバッグ] ボタンを選択します。 または、F5 キー (デバッグの開始) を押します。 UI 上部のコマンド パレットで C# デバッガーを選択します。 サーバー プロジェクトの既定のプロファイルを選択します (例: C#:BlazorSample [Default Configuration])。
4. ブラウザーで、Counter (/counter) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。
5. UI で [続行] ボタンを選択するか、F5 (Continue) キーを押して実行を続行します。

ブレークポイントには、サーバー プロジェクトからヒットすることもできます。

1. [停止] ボタンを選択するか、キーボードの Shift+F5 キーを押してデバッグを停止します。

2. 次のコンポーネントをサーバー アプリに追加します。 このコンポーネントによって "対話型サーバー" レンダリング モード (InteractiveServer) が採用されます。

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Counter2 コンポーネントで currentCount++; の行にブレークポイントを設定します。

4. UI で [デバッグの開始] ボタンを選択するか、F5 キー (デバッグの開始) を押してデバッガーでアプリを実行します。

5. ブラウザーで、Counter2 (/counter-2) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。

6. UI で [続行] ボタンを選択するか、F5 (Continue) キーを押して実行を続行します。

デバッグ プロキシが実行状態になる前のアプリの起動中には、ブレークポイントで停止することはありません。 これには、Program ファイルのブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。

[デバッグなしで開始] [Ctrl+F5 キー (Windows) または ⌘+F5 キー (macOS)] はサポートされていません。 アプリがデバッグ構成で実行されている場合、デバッグのオーバーヘッドによって常にパフォーマンスがわずかに低下します。

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

Visual Studio

1. アプリを開く
2. Counter コンポーネント (Pages/Counter.razor) で currentCount++; の行にブレークポイントを設定します。
3. F5 キーを押して、デバッガーでアプリを実行します。
4. ブラウザーで、Counter (/counter) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。
5. Visual Studio の [ローカル] ウィンドウで、currentCount フィールドの値を調べます。
6. F5 キーを押して、実行を続行します。

デバッグ プロキシが実行状態になる前のアプリの起動中には、ブレークポイントで停止することはありません。 これには、Program ファイルのブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。

Visual Studio Code

1. Visual Studio Code でアプリのフォルダーを開きます。
2. Counter コンポーネント (Pages/Counter.razor) で currentCount++; の行にブレークポイントを設定します。
3. [実行とデバッグ] ウィンドウを開き、[実行とデバッグ] ボタンを選択します。 または、F5 キー (デバッグの開始) を押します。 UI 上部のコマンド パレットで C# デバッガーを選択します。 既定のプロファイル (たとえば C#:BlazorSample [Default Configuration]) を選択します。
4. F5 キーを押して、デバッガーでアプリを実行します。
5. スタンドアロン アプリが起動され、デバッグ ブラウザーが開きます。
6. ブラウザーで、Counter (/counter) に移動します。 デバッグ プロキシが読み込んで実行されるまで数秒待ちます。 [ここをクリック] ボタンを選んで、ブレークポイントにヒットします。
7. F5 キーを押して、実行を続行します。

デバッグ プロキシが実行状態になる前のアプリの起動中には、ブレークポイントで停止することはありません。 これには、Program ファイルのブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。

[デバッグなしで開始] [Ctrl+F5 キー (Windows) または ⌘+F5 キー (macOS)] はサポートされていません。 アプリがデバッグ構成で実行されている場合、デバッグのオーバーヘッドによって常にパフォーマンスがわずかに低下します。

デバッガーのサポート

<DebuggerSupport>{VALUE}</DebuggerSupport> でデバッガーのサポートが有効になっているときに、{VALUE} プレースホルダーが true または false のいずれかである場合、ランタイムのデバッグが有効になります。

Blazor フレームワークの既定では、デバッグ以外のすべての構成に対してデバッガーのサポートが "無効" になります。 デバッグ以外の構成に対するデバッガーのサポートを有効にするには、アプリのプロジェクト ファイルに <DebuggerSupport> プロパティを追加します。

次の例では、カスタム "DebugCustom" 構成に対してデバッガーのサポートが有効になっています。

<DebuggerSupport Condition="'$(Configuration)' == 'DebugCustom'">true</DebuggerSupport>

詳細については、「Blazor WebAssembly カスタム デバッガーの構成 (dotnet/runtime #96239)」を参照してください。

既存の 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)。

オプション	説明
browser	デバッグ セッション用に起動するブラウザー。 edge または chrome に設定します。 既定値は edge です。
cwd	アプリを起動する作業ディレクトリ。
request	launch を使用して、Blazor WebAssembly アプリにデバッグ セッションを起動してアタッチするか、attach を使用して既に実行中のアプリにデバッグ セッションをアタッチします。
timeout	デバッグ セッションがアタッチされるのを待機するミリ秒単位の時間。 既定値は 30,000 ミリ秒 (30 秒) です。
trace	JS デバッガーからログを生成するために使用されます。 ログを生成するには true に設定します。
url	デバッグ時にブラウザーで開く URL。
webRoot	Web サーバーの絶対パスを指定します。 アプリをサブルートから提供する場合は設定する必要があります。

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

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

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

1. 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 を指し示します。 プロキシは、デバッグしようとしているブラウザー ウィンドウに接続します (そのためリモート デバッグを有効にする必要があります)。

Firefox を使用して Blazor WebAssembly アプリをデバッグする

このセクションのガイダンスは、Windows で実行されている Firefox での Blazor WebAssembly アプリのデバッグに適用されます。

Firefox を使って Blazor WebAssembly アプリをデバッグするには、リモート デバッグ用にブラウザーを構成し、.NET WebAssembly デバッグ プロキシを介してブラウザー開発者ツールを使ってブラウザーに接続する必要があります。

Note

現在のところ、Visual Studio からの Firefox でのデバッグはサポートされていません。

開発中に Firefox で Blazor WebAssembly アプリをデバッグするには:

1. Firefox を構成する:
   • 新しいブラウザー タブで about:config を開きます。表示される警告を読んで閉じます。
   • devtools.debugger.remote-enabled を有効にするには、その値を True に設定します。
   • devtools.chrome.enabled を有効にするには、その値を True に設定します。
   • devtools.debugger.prompt-connection を無効にするには、その値を False に設定します。
2. すべての Firefox インスタンスを閉じます。
3. dotnet run を使用して、コマンド シェルでアプリを実行します。
4. Firefox ブラウザーを再起動し、アプリに移動します。
5. 新しいブラウザー タブで about:debugging を開きます。このタブは開いたままにしておきます。
6. アプリが実行されているタブに戻ります。 Shift+Alt+d キーを押してリモート デバッグを開始します。
7. [Debugger] タブで、file:// ノード以下にあるデバッグ対象のアプリ ソース ファイルを開き、ブレークポイントを設定します。 たとえば、Counter コンポーネント (Pages/Counter.razor) で IncrementCount メソッドの currentCount++; 行にブレークポイントを設定します。
8. アプリのブラウザー タブで、Counter コンポーネント ページ (/counter) に移動し、カウンター ボタンを選んでブレークポイントにヒットします。
9. F5 キーを押して、デバッグ タブで実行を続行します。

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

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

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

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

ブラウザー ソース マップ

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

ファイアウォールの構成

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

警告

セキュリティの脆弱性が発生しないようにするには、ファイアウォールの構成を慎重に変更する必要があります。 セキュリティ ガイダンスを慎重に適用し、セキュリティに関するベスト プラクティスに従い、ファイアウォールの製造元から発行された警告を順守します。

NodeJS プロセスとのオープンな通信を許可する:

• ファイアウォールの機能と構成に応じて、Node サーバーが開いて接続されます。
• ネットワークによっては危険な場合があります。
• 開発者のマシンでのみ行うことをお勧めします。

可能な場合は、信頼されているネットワークまたはプライベート ネットワーク上の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 として割り当てられます。