ASP.NET Core Blazor WebAssembly をデバッグする

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

Blazor WebAssembly アプリは、Chromium ベースのブラウザー (Edge/Chrome) のブラウザー開発者ツールを使用してデバッグできます。 次の IDE を使用してアプリをデバッグすることもできます。

  • Visual Studio
  • Visual Studio for Mac
  • Visual Studio Code

利用可能なシナリオには以下が含まれます。

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

現時点では、次の操作を行うことはできません

  • 未処理の例外の発生時に中断する。
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。 これには、Program.cs のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。
  • ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL)Visual Studio Codespaces) でデバッグします。
  • dotnet watch run を使用してアプリを実行するなどして、デバッグ中にホステッド Blazor WebAssemblyソリューションのバックエンド Server アプリを自動的に再構築します。

必須コンポーネント

デバッグには、次のいずれかのブラウザーが必要です。

  • Google Chrome (バージョン 70 以降) (既定値)
  • Microsoft Edge (バージョン 80 以降)

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

Visual Studio Code ユーザーには、次の拡張機能が必要です。

VS コードでプロジェクトを開いた後に、デバッグを有効にするために追加の設定が必要であることを示す通知が表示される場合があります。 要求された場合は、Visual Studio Marketplace から必要な拡張機能をインストールします。 インストールされている拡張機能を確認するには、メニュー バーから [表示]>[拡張機能] を開くか、アクティビティ サイド バーにある拡張機能アイコンを選択します。

Visual Studio for Mac のバージョン 8.8 (ビルド 1532) 以降が必要です。

Visual Studio for Mac の最新リリースをインストールします。それには、 [Visual Studio for Mac をダウンロードする] ボタンを選択します (Microsoft: Visual Studio for Mac)。

Note

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

パッケージ

スタンドアロン Blazor WebAssembly:

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

ホステッド Blazor WebAssembly:

Note

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

スタンドアロン Blazor WebAssembly アプリをデバッグする

既存の Blazor WebAssembly アプリのデバッグを有効にするには、スタートアップ プロジェクトの launchSettings.json ファイルを更新して、各起動プロファイルに次の inspectUri プロパティを含めます。

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

更新されると、launchSettings.json ファイルは次の例のようになります。

{
    "iisSettings": {
      "windowsAuthentication": false,
      "anonymousAuthentication": true,
      "iisExpress": {
        "applicationUrl": "http://localhost:50454",
        "sslPort": 44399
      }
    },
    "profiles": {
      "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
      "BlazorApp1.Server": {
        "commandName": "Project",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "applicationUrl": "https://localhost:5001;http://localhost:5000",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      }
    }
  }

inspectUri プロパティ:

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

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

Visual Studio で Blazor WebAssembly アプリをデバッグするには、次のようにします。

  1. ホステッド Blazor WebAssemblyソリューションを新規作成します。

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

    Note

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

    注意

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

  3. "Client" アプリで、Pages/Counter.razorcurrentCount++; 行にブレークポイントを設定します。

  4. ブラウザーで Counter ページに移動し、 [Click me] ボタンを選択して、ブレークポイントで停止させます。

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

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

Blazor WebAssembly アプリをデバッグしている間に、サーバー コードをデバッグすることもできます。

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

Note

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

アプリが / 以外のアプリ ベース パスでホストされている場合、Properties/launchSettings.json で次のプロパティを更新し、アプリのベース パスを反映させます。

  • applicationUrl:

    "iisSettings": {
      ...
      "iisExpress": {
        "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/",
        "sslPort": {SECURE PORT}
      }
    },
    
  • 各プロファイルの inspectUri:

    "profiles": {
      ...
      "{PROFILE 1, 2, ... N}": {
        ...
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        ...
      }
    }
    

前の設定のプレースホルダー:

  • {INSECURE PORT}:セキュリティで保護されていないポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {APP BASE PATH}:アプリのベース パス。
  • {SECURE PORT}:セキュリティで保護されているポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {PROFILE 1, 2, ... N}:起動設定プロファイル。 通常、既定では、1 つのアプリから複数のプロファイルが指定されます (たとえば、IIS Express 用のプロファイルと、Kestrel サーバーで使用されるプロジェクト プロファイル)。

次の例では、アプリは /OAT でホストされており、アプリ ベース パスは <base href="/OAT/"> として wwwroot/index.html に構成されています。

"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",

Blazor WebAssembly アプリにカスタム アプリ ベース パスを使用する方法については、「ASP.NET Core Blazor のホストと展開」をご覧ください。

ブラウザーでデバッグする

このセクションのガイダンスは、Windows で実行されている Google Chrome と Microsoft Edge に適用されます。

  1. 開発環境でアプリのデバッグ ビルドを実行します。

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

  3. ブラウザーで Shift+Alt+D キーを押すことにより、リモート デバッグの開始を試みます。

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

  1. リモート デバッグが有効な状態でブラウザーが実行されていると、前のステップのデバッグ キーボード ショートカットにより、新しいデバッガー タブが開きます。

  2. 少しすると、 [ソース] タブに、file:// ノード内にあるアプリの .NET アセンブリの一覧が表示されます。

  3. コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) で、設定したブレークポイントがコードの実行時にヒットします。 ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、コードの実行を普通に再開 (F8) します。

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

ブラウザー ソース マップ

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

ファイアウォールの構成

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

警告

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

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

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

可能な場合は、信頼されているネットワークまたはプライベート ネットワーク上のNodeJS プロセスとのオープン通信のみを許可します。

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

トラブルシューティング

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

  • [デバッガー] タブで、ブラウザー内の開発者ツールを開きます。 コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。
  • ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。 詳細については、「ASP.NET Core で HTTPS を適用する」を参照してください。
  • Visual Studio では、 [ツール]>[オプション]>[デバッグ]>[全般][Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE)] (ASP.NET (Chrome、Edge、IE) の 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 として割り当てられます。

Blazor WebAssembly アプリは、Chromium ベースのブラウザー (Edge/Chrome) のブラウザー開発者ツールを使用してデバッグできます。 次の IDE を使用してアプリをデバッグすることもできます。

  • Visual Studio
  • Visual Studio for Mac
  • Visual Studio Code

利用可能なシナリオには以下が含まれます。

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

現時点では、次の操作を行うことはできません

  • 未処理の例外の発生時に中断する。
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。 これには、Program.cs のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。
  • ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL)Visual Studio Codespaces) でデバッグします。
  • dotnet watch run を使用してアプリを実行するなどして、デバッグ中にホステッド Blazor WebAssemblyソリューションのバックエンド Server アプリを自動的に再構築します。

必須コンポーネント

デバッグには、次のいずれかのブラウザーが必要です。

  • Google Chrome (バージョン 70 以降) (既定値)
  • Microsoft Edge (バージョン 80 以降)

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

Visual Studio Code ユーザーには、次の拡張機能が必要です。

VS コードでプロジェクトを開いた後に、デバッグを有効にするために追加の設定が必要であることを示す通知が表示される場合があります。 要求された場合は、Visual Studio Marketplace から必要な拡張機能をインストールします。 インストールされている拡張機能を確認するには、メニュー バーから [表示]>[拡張機能] を開くか、アクティビティ サイド バーにある拡張機能アイコンを選択します。

Visual Studio for Mac のバージョン 8.8 (ビルド 1532) 以降が必要です。

Visual Studio for Mac の最新リリースをインストールします。それには、 [Visual Studio for Mac をダウンロードする] ボタンを選択します (Microsoft: Visual Studio for Mac)。

Note

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

パッケージ

スタンドアロン Blazor WebAssembly:

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

ホステッド Blazor WebAssembly:

Note

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

スタンドアロン Blazor WebAssembly アプリをデバッグする

既存の Blazor WebAssembly アプリのデバッグを有効にするには、スタートアップ プロジェクトの launchSettings.json ファイルを更新して、各起動プロファイルに次の inspectUri プロパティを含めます。

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

更新されると、launchSettings.json ファイルは次の例のようになります。

{
    "iisSettings": {
      "windowsAuthentication": false,
      "anonymousAuthentication": true,
      "iisExpress": {
        "applicationUrl": "http://localhost:50454",
        "sslPort": 44399
      }
    },
    "profiles": {
      "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
      "BlazorApp1.Server": {
        "commandName": "Project",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "applicationUrl": "https://localhost:5001;http://localhost:5000",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      }
    }
  }

inspectUri プロパティ:

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

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

Visual Studio で Blazor WebAssembly アプリをデバッグするには、次のようにします。

  1. ホステッド Blazor WebAssemblyソリューションを新規作成します。

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

    Note

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

    注意

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

  3. "Client" アプリで、Pages/Counter.razorcurrentCount++; 行にブレークポイントを設定します。

  4. ブラウザーで Counter ページに移動し、 [Click me] ボタンを選択して、ブレークポイントで停止させます。

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

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

Blazor WebAssembly アプリをデバッグしている間に、サーバー コードをデバッグすることもできます。

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

Note

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

アプリが / 以外のアプリ ベース パスでホストされている場合、Properties/launchSettings.json で次のプロパティを更新し、アプリのベース パスを反映させます。

  • applicationUrl:

    "iisSettings": {
      ...
      "iisExpress": {
        "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/",
        "sslPort": {SECURE PORT}
      }
    },
    
  • 各プロファイルの inspectUri:

    "profiles": {
      ...
      "{PROFILE 1, 2, ... N}": {
        ...
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        ...
      }
    }
    

前の設定のプレースホルダー:

  • {INSECURE PORT}:セキュリティで保護されていないポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {APP BASE PATH}:アプリのベース パス。
  • {SECURE PORT}:セキュリティで保護されているポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {PROFILE 1, 2, ... N}:起動設定プロファイル。 通常、既定では、1 つのアプリから複数のプロファイルが指定されます (たとえば、IIS Express 用のプロファイルと、Kestrel サーバーで使用されるプロジェクト プロファイル)。

次の例では、アプリは /OAT でホストされており、アプリ ベース パスは <base href="/OAT/"> として wwwroot/index.html に構成されています。

"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",

Blazor WebAssembly アプリにカスタム アプリ ベース パスを使用する方法については、「ASP.NET Core Blazor のホストと展開」をご覧ください。

ブラウザーでデバッグする

このセクションのガイダンスは、Windows で実行されている Google Chrome と Microsoft Edge に適用されます。

  1. 開発環境でアプリのデバッグ ビルドを実行します。

  2. ブラウザーを起動し、アプリの URL (https://localhost:7268 など) に移動します。

  3. ブラウザーで Shift+Alt+D キーを押すことにより、リモート デバッグの開始を試みます。

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

  1. リモート デバッグが有効な状態でブラウザーが実行されていると、前のステップのデバッグ キーボード ショートカットにより、新しいデバッガー タブが開きます。

  2. 少しすると、 [ソース] タブに、file:// ノード内にあるアプリの .NET アセンブリの一覧が表示されます。

  3. コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) で、設定したブレークポイントがコードの実行時にヒットします。 ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、コードの実行を普通に再開 (F8) します。

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

ブラウザー ソース マップ

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

ファイアウォールの構成

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

警告

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

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

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

可能な場合は、信頼されているネットワークまたはプライベート ネットワーク上のNodeJS プロセスとのオープン通信のみを許可します。

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

トラブルシューティング

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

  • [デバッガー] タブで、ブラウザー内の開発者ツールを開きます。 コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。
  • ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。 詳細については、「ASP.NET Core で HTTPS を適用する」を参照してください。
  • Visual Studio では、 [ツール]>[オプション]>[デバッグ]>[全般][Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE)] (ASP.NET (Chrome、Edge、IE) の 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 として割り当てられます。

Blazor WebAssembly アプリは、Chromium ベースのブラウザー (Edge/Chrome) のブラウザー開発者ツールを使用してデバッグできます。 次の IDE を使用してアプリをデバッグすることもできます。

  • Visual Studio
  • Visual Studio for Mac
  • Visual Studio Code

利用可能なシナリオには以下が含まれます。

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

現時点では、次の操作を行うことはできません

  • 未処理の例外の発生時に中断する。
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。 これには、Program.cs のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。
  • ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL)Visual Studio Codespaces) でデバッグします。
  • dotnet watch run を使用してアプリを実行するなどして、デバッグ中にホステッド Blazor WebAssemblyソリューションのバックエンド Server アプリを自動的に再構築します。

必須コンポーネント

デバッグには、次のいずれかのブラウザーが必要です。

  • Google Chrome (バージョン 70 以降) (既定値)
  • Microsoft Edge (バージョン 80 以降)

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

Visual Studio Code ユーザーには、次の拡張機能が必要です。

VS コードでプロジェクトを開いた後に、デバッグを有効にするために追加の設定が必要であることを示す通知が表示される場合があります。 要求された場合は、Visual Studio Marketplace から必要な拡張機能をインストールします。 インストールされている拡張機能を確認するには、メニュー バーから [表示]>[拡張機能] を開くか、アクティビティ サイド バーにある拡張機能アイコンを選択します。

Visual Studio for Mac のバージョン 8.8 (ビルド 1532) 以降が必要です。

Visual Studio for Mac の最新リリースをインストールします。それには、 [Visual Studio for Mac をダウンロードする] ボタンを選択します (Microsoft: Visual Studio for Mac)。

Note

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

パッケージ

スタンドアロン Blazor WebAssembly:

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

ホステッド Blazor WebAssembly:

Note

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

スタンドアロン Blazor WebAssembly アプリをデバッグする

既存の Blazor WebAssembly アプリのデバッグを有効にするには、スタートアップ プロジェクトの launchSettings.json ファイルを更新して、各起動プロファイルに次の inspectUri プロパティを含めます。

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

更新されると、launchSettings.json ファイルは次の例のようになります。

{
    "iisSettings": {
      "windowsAuthentication": false,
      "anonymousAuthentication": true,
      "iisExpress": {
        "applicationUrl": "http://localhost:50454",
        "sslPort": 44399
      }
    },
    "profiles": {
      "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
      "BlazorApp1.Server": {
        "commandName": "Project",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "applicationUrl": "https://localhost:5001;http://localhost:5000",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      }
    }
  }

inspectUri プロパティ:

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

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

Visual Studio で Blazor WebAssembly アプリをデバッグするには、次のようにします。

  1. ホステッド Blazor WebAssemblyソリューションを新規作成します。

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

    Note

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

    注意

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

  3. "Client" アプリで、Pages/Counter.razorcurrentCount++; 行にブレークポイントを設定します。

  4. ブラウザーで Counter ページに移動し、 [Click me] ボタンを選択して、ブレークポイントで停止させます。

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

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

Blazor WebAssembly アプリをデバッグしている間に、サーバー コードをデバッグすることもできます。

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

Note

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

アプリが / 以外のアプリ ベース パスでホストされている場合、Properties/launchSettings.json で次のプロパティを更新し、アプリのベース パスを反映させます。

  • applicationUrl:

    "iisSettings": {
      ...
      "iisExpress": {
        "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/",
        "sslPort": {SECURE PORT}
      }
    },
    
  • 各プロファイルの inspectUri:

    "profiles": {
      ...
      "{PROFILE 1, 2, ... N}": {
        ...
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        ...
      }
    }
    

前の設定のプレースホルダー:

  • {INSECURE PORT}:セキュリティで保護されていないポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {APP BASE PATH}:アプリのベース パス。
  • {SECURE PORT}:セキュリティで保護されているポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {PROFILE 1, 2, ... N}:起動設定プロファイル。 通常、既定では、1 つのアプリから複数のプロファイルが指定されます (たとえば、IIS Express 用のプロファイルと、Kestrel サーバーで使用されるプロジェクト プロファイル)。

次の例では、アプリは /OAT でホストされており、アプリ ベース パスは <base href="/OAT/"> として wwwroot/index.html に構成されています。

"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",

Blazor WebAssembly アプリにカスタム アプリ ベース パスを使用する方法については、「ASP.NET Core Blazor のホストと展開」をご覧ください。

ブラウザーでデバッグする

このセクションのガイダンスは、Windows で実行されている Google Chrome と Microsoft Edge に適用されます。

  1. 開発環境でアプリのデバッグ ビルドを実行します。

  2. ブラウザーを起動し、アプリの URL (https://localhost:5001 など) に移動します。

  3. ブラウザーで Shift+Alt+D キーを押すことにより、リモート デバッグの開始を試みます。

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

  1. リモート デバッグが有効な状態でブラウザーが実行されていると、前のステップのデバッグ キーボード ショートカットにより、新しいデバッガー タブが開きます。

  2. 少しすると、 [ソース] タブに、file:// ノード内にあるアプリの .NET アセンブリの一覧が表示されます。

  3. コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) で、設定したブレークポイントがコードの実行時にヒットします。 ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、コードの実行を普通に再開 (F8) します。

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

ブラウザー ソース マップ

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

ファイアウォールの構成

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

警告

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

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

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

可能な場合は、信頼されているネットワークまたはプライベート ネットワーク上のNodeJS プロセスとのオープン通信のみを許可します。

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

トラブルシューティング

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

  • [デバッガー] タブで、ブラウザー内の開発者ツールを開きます。 コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。
  • ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。 詳細については、「ASP.NET Core で HTTPS を適用する」を参照してください。
  • Visual Studio では、 [ツール]>[オプション]>[デバッグ]>[全般][Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE)] (ASP.NET (Chrome、Edge、IE) の 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 として割り当てられます。

Blazor WebAssembly アプリは、Chromium ベースのブラウザー (Edge/Chrome) のブラウザー開発者ツールを使用してデバッグできます。 次の IDE を使用してアプリをデバッグすることもできます。

  • Visual Studio
  • Visual Studio for Mac
  • Visual Studio Code

利用可能なシナリオには以下が含まれます。

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

現時点では、次の操作を行うことはできません

  • 未処理の例外の発生時に中断する。
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。 これには、Program.cs のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} ライフサイクル メソッドのブレークポイントが含まれます。
  • ローカル以外のシナリオ (たとえば、Linux 用 Windows サブシステム (WSL)Visual Studio Codespaces) でデバッグします。
  • dotnet watch run を使用してアプリを実行するなどして、デバッグ中にホステッド Blazor WebAssemblyソリューションのバックエンド Server アプリを自動的に再構築します。

必須コンポーネント

デバッグには、次のいずれかのブラウザーが必要です。

  • Google Chrome (バージョン 70 以降) (既定値)
  • Microsoft Edge (バージョン 80 以降)

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

Visual Studio Code ユーザーには、次の拡張機能が必要です。

VS コードでプロジェクトを開いた後に、デバッグを有効にするために追加の設定が必要であることを示す通知が表示される場合があります。 要求された場合は、Visual Studio Marketplace から必要な拡張機能をインストールします。 インストールされている拡張機能を確認するには、メニュー バーから [表示]>[拡張機能] を開くか、アクティビティ サイド バーにある拡張機能アイコンを選択します。

Visual Studio for Mac のバージョン 8.8 (ビルド 1532) 以降が必要です。

Visual Studio for Mac の最新リリースをインストールします。それには、 [Visual Studio for Mac をダウンロードする] ボタンを選択します (Microsoft: Visual Studio for Mac)。

Note

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

パッケージ

スタンドアロン Blazor WebAssembly:

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

ホステッド Blazor WebAssembly:

Note

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

スタンドアロン Blazor WebAssembly アプリをデバッグする

既存の Blazor WebAssembly アプリのデバッグを有効にするには、スタートアップ プロジェクトの launchSettings.json ファイルを更新して、各起動プロファイルに次の inspectUri プロパティを含めます。

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

更新されると、launchSettings.json ファイルは次の例のようになります。

{
    "iisSettings": {
      "windowsAuthentication": false,
      "anonymousAuthentication": true,
      "iisExpress": {
        "applicationUrl": "http://localhost:50454",
        "sslPort": 44399
      }
    },
    "profiles": {
      "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
      "BlazorApp1.Server": {
        "commandName": "Project",
        "launchBrowser": true,
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        "applicationUrl": "https://localhost:5001;http://localhost:5000",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      }
    }
  }

inspectUri プロパティ:

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

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

Visual Studio で Blazor WebAssembly アプリをデバッグするには、次のようにします。

  1. ホステッド Blazor WebAssemblyソリューションを新規作成します。

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

    Note

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

    注意

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

  3. "Client" アプリで、Pages/Counter.razorcurrentCount++; 行にブレークポイントを設定します。

  4. ブラウザーで Counter ページに移動し、 [Click me] ボタンを選択して、ブレークポイントで停止させます。

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

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

Blazor WebAssembly アプリをデバッグしている間に、サーバー コードをデバッグすることもできます。

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

Note

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

アプリが / 以外のアプリ ベース パスでホストされている場合、Properties/launchSettings.json で次のプロパティを更新し、アプリのベース パスを反映させます。

  • applicationUrl:

    "iisSettings": {
      ...
      "iisExpress": {
        "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/",
        "sslPort": {SECURE PORT}
      }
    },
    
  • 各プロファイルの inspectUri:

    "profiles": {
      ...
      "{PROFILE 1, 2, ... N}": {
        ...
        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}",
        ...
      }
    }
    

前の設定のプレースホルダー:

  • {INSECURE PORT}:セキュリティで保護されていないポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {APP BASE PATH}:アプリのベース パス。
  • {SECURE PORT}:セキュリティで保護されているポート。 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。
  • {PROFILE 1, 2, ... N}:起動設定プロファイル。 通常、既定では、1 つのアプリから複数のプロファイルが指定されます (たとえば、IIS Express 用のプロファイルと、Kestrel サーバーで使用されるプロジェクト プロファイル)。

次の例では、アプリは /OAT でホストされており、アプリ ベース パスは <base href="/OAT/"> として wwwroot/index.html に構成されています。

"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",

Blazor WebAssembly アプリにカスタム アプリ ベース パスを使用する方法については、「ASP.NET Core Blazor のホストと展開」をご覧ください。

ブラウザーでデバッグする

このセクションのガイダンスは、Windows で実行されている Google Chrome と Microsoft Edge に適用されます。

  1. 開発環境でアプリのデバッグ ビルドを実行します。

  2. ブラウザーを起動し、アプリの URL (https://localhost:5001 など) に移動します。

  3. ブラウザーで Shift+Alt+D キーを押すことにより、リモート デバッグの開始を試みます。

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

  1. リモート デバッグが有効な状態でブラウザーが実行されていると、前のステップのデバッグ キーボード ショートカットにより、新しいデバッガー タブが開きます。

  2. 少しすると、 [ソース] タブに、file:// ノード内にあるアプリの .NET アセンブリの一覧が表示されます。

  3. コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) で、設定したブレークポイントがコードの実行時にヒットします。 ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、コードの実行を普通に再開 (F8) します。

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

ブラウザー ソース マップ

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

ファイアウォールの構成

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

警告

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

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

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

可能な場合は、信頼されているネットワークまたはプライベート ネットワーク上のNodeJS プロセスとのオープン通信のみを許可します。

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

トラブルシューティング

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

  • [デバッガー] タブで、ブラウザー内の開発者ツールを開きます。 コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。
  • ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。 詳細については、「ASP.NET Core で HTTPS を適用する」を参照してください。
  • Visual Studio では、 [ツール]>[オプション]>[デバッグ]>[全般][Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE)] (ASP.NET (Chrome、Edge、IE) の 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 として割り当てられます。