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

Note

これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の ASP.NET Core 8.0 バージョンを参照してください。

この記事では、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 の基本設定で構成したデバッグのシンボル サーバーを使います。

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

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

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

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

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

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

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

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

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

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

  • ブレークポイントの設定と削除を行う。
  • IDE でデバッグ サポートを使用してアプリを実行する。
  • コードを 1 ステップずつ実行する。
  • IDE でキーボード ショートカットを使用してコード実行を再開する。
  • [ローカル] ウィンドウで、ローカル変数の値を観察する。
  • JavaScript と .NET の間の呼び出しチェーンなど、呼び出し履歴を確認する。
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。 これには、Program ファイルのブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。
  • ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL)Visual Studio Codespaces) でデバッグします。
  • デバッグにはシンボル サーバーを使います。

前提条件

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

ブラウザーの前提条件

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

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

デバッグには、次のブラウザーの最新バージョンが必要です。

  • Google Chrome (既定値)
  • Microsoft Edge

ファイアウォールまたはプロキシでデバッグ プロキシ (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# Dev Kit in the Visual Studio Code Extensions Marketplace

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

警告やエラーが発生した場合は、イシューを提起し (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 Server: Microsoft.AspNetCore.Components.WebAssembly.Server: ブラウザー デバッグ ホストを共有するアセンブリの内部パッケージ (Microsoft.NETCore.BrowserDebugHost.Transport) を参照します。

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

ホステッド Blazor WebAssembly:

Note

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

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

このセクションの例では、対話型レンダリング モードが "自動" (サーバーと 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} ライフサイクル メソッドのブレークポイントが含まれます。

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

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

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

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

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

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

IDE でホストされた Blazor WebAssembly アプリをデバッグする

  1. ソリューション エクスプローラーServer プロジェクトを選択し、F5 キーを押して、デバッガーでアプリを実行します。

    Google Chrome や Microsoft Edge などの Chromium ベースのブラウザーでデバッグする場合、ユーザーのプロファイルを含む既存のブラウザー ウィンドウでタブが開かれるのではなく、デバッグ セッション用の別のプロファイルで新しいブラウザー ウィンドウが開かれる場合があります。 ユーザーのプロファイルを使用してデバッグする必要がある場合は、次のアプローチのいずれかを採用してください。

  2. Client プロジェクトで、Counter コンポーネント (Pages/Counter.razor) で currentCount++; の行にブレークポイントを設定します。

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

  4. Visual Studio の [ローカル] ウィンドウで、currentCount フィールドの値を調べます。

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

Server プロジェクトのサーバー コードをデバッグすることもできます。

  1. Pages/FetchData.razor ページの OnInitializedAsync にブレークポイントを設定します。
  2. Get アクション メソッドの WeatherForecastController にブレークポイントを設定します。
  3. Fetch Data ページに移動し、サーバーに HTTP 要求を発行する直前の、FetchData コンポーネント内の最初のブレークポイントで停止させます。
  4. F5 キーを押して実行を続け、サーバーの WeatherForecastController 内のブレークポイントで停止させます。
  5. F5 キーをもう一度押して実行を続け、天気予報テーブルがブラウザーにレンダリングされることを確認します。

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

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

既存の 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 サーバーの絶対パスを指定します。 アプリをサブルートから提供する場合は設定する必要があります。

次のテーブルに記載の追加のオプションは、ホストされた Blazor WebAssembly アプリにのみ適用されます。

オプション 説明
env 起動されたプロセスに提供する環境変数。 hostedtrueに設定されている場合にのみ適用されます。
hosted ホストされている Blazor WebAssembly アプリを起動およびデバッグする場合は、true に設定する必要があります。
program ホストされたアプリのサーバーを実行する実行可能ファイルへの参照。 hostedtrue の場合に設定する必要があります。

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 として割り当てられます。