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

Daniel RothDaniel Roth

Blazor WebAssembly アプリは、Chromium ベースのブラウザー (Edge/Chrome) のブラウザー開発ツールを使用してデバッグできます。Blazor WebAssembly apps can be debugged using the browser dev tools in Chromium-based browsers (Edge/Chrome). 次の統合開発環境 (IDE) を使用して、アプリをデバッグすることもできます。You can also debug your app using the following integrated development environments (IDEs):

  • Visual StudioVisual Studio
  • Visual Studio for MacVisual Studio for Mac
  • Visual Studio CodeVisual Studio Code

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

  • ブレークポイントの設定と削除を行う。Set and remove breakpoints.
  • IDE でデバッグ サポートを使用してアプリを実行する。Run the app with debugging support in IDEs.
  • コードを 1 ステップずつ実行する。Single-step through the code.
  • IDE でキーボード ショートカットを使用してコード実行を再開する。Resume code execution with a keyboard shortcut in IDEs.
  • [ローカル] ウィンドウで、ローカル変数の値を観察する。In the Locals window, observe the values of local variables.
  • JavaScript と .NET の間の呼び出しチェーンなど、呼び出し履歴を確認する。See the call stack, including call chains between JavaScript and .NET.

現時点では、次の操作を行うことはできませんFor now, you can't:

  • 未処理の例外の発生時に中断する。Break on unhandled exceptions.
  • デバッグ プロキシが実行される前に、アプリの起動中にブレークポイントにヒットします。Hit breakpoints during app startup before the debug proxy is running. これには、Program.Main (Program.cs) のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} メソッドのブレークポイントが含まれます。This includes breakpoints in Program.Main (Program.cs) and breakpoints in the OnInitialized{Async} methods of components that are loaded by the first page requested from the app.

必須コンポーネントPrerequisites

デバッグには、次のいずれかのブラウザーが必要です。Debugging requires either of the following browsers:

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

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

  1. Visual Studio for Mac の最新リリースをインストールします。それには、 [Visual Studio for Mac をダウンロードする] ボタンを選択します (Microsoft: Visual Studio for Mac)。Install the latest release of Visual Studio for Mac by selecting the Download Visual Studio for Mac button at Microsoft: Visual Studio for Mac.
  2. Visual Studio 内から "プレビュー" チャネルを選択します。Select the Preview channel from within Visual Studio. 詳細については、「Visual Studio for Mac のプレビュー バージョンをインストールする」を参照してください。For more information, see Install a preview version of Visual Studio for Mac.

注意

現在、macOS での Apple Safari はサポートされていません。Apple Safari on macOS isn't currently supported.

デバッグの有効化Enable debugging

既存の Blazor WebAssembly アプリのデバッグを有効にするには、スタートアップ プロジェクトの launchSettings.json ファイルを更新して、各起動プロファイルに次の inspectUri プロパティを含めます。To enable debugging for an existing Blazor WebAssembly app, update the launchSettings.json file in the startup project to include the following inspectUri property in each launch profile:

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

更新されると、launchSettings.json ファイルは次の例のようになります。Once updated, the launchSettings.json file should look similar to the following example:

{
  "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 プロパティ:The inspectUri property:

  • アプリが Blazor WebAssembly アプリであることを IDE で検出できるようにします。Enables the IDE to detect that the app is a Blazor WebAssembly app.
  • スクリプト デバッグ インフラストラクチャに対して、Blazor のデバッグ プロキシを使用してブラウザーに接続するように指示します。Instructs the script debugging infrastructure to connect to the browser through Blazor's debugging proxy.

起動したブラウザー (browserInspectUri) の Websocket プロトコル (wsProtocol)、ホスト (url.hostname)、ポート (url.port)、およびインスペクター URI のプレースホルダー値は、フレームワークによって提供されます。The placeholder values for the WebSockets protocol (wsProtocol), host (url.hostname), port (url.port), and inspector URI on the launched browser (browserInspectUri) are provided by the framework.

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

  1. 新しい ASP.NET Core でホストされる Blazor WebAssembly アプリを作成します。Create a new ASP.NET Core hosted Blazor WebAssembly app.

  2. F5 キーを押して、デバッガーでアプリを実行します。Press F5 to run the app in the debugger.

    注意

    デバッグなしの開始 (Ctrl+F5) はサポートされていません。Start Without Debugging (Ctrl+F5) isn't supported. アプリがデバッグ構成で実行されている場合、デバッグのオーバーヘッドによって常にパフォーマンスがわずかに低下します。When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.

  3. "*Client*" アプリで、Pages/Counter.razorcurrentCount++; 行にブレークポイントを設定します。In the *Client* app, set a breakpoint on the currentCount++; line in Pages/Counter.razor.

  4. ブラウザーで Counter ページに移動し、 [Click me] ボタンを選択して、ブレークポイントで停止させます。In the browser, navigate to Counter page and select the Click me button to hit the breakpoint.

  5. Visual Studio の [ローカル] ウィンドウで、currentCount フィールドの値を調べます。In Visual Studio, inspect the value of the currentCount field in the Locals window.

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

Blazor WebAssembly アプリをデバッグしている間に、サーバー コードをデバッグすることもできます。While debugging a Blazor WebAssembly app, you can also debug server code:

  1. Pages/FetchData.razor ページの OnInitializedAsync にブレークポイントを設定します。Set a breakpoint in the Pages/FetchData.razor page in OnInitializedAsync.
  2. Get アクション メソッドの WeatherForecastController にブレークポイントを設定します。Set a breakpoint in the WeatherForecastController in the Get action method.
  3. Fetch Data ページに移動し、サーバーに HTTP 要求を発行する直前の、FetchData コンポーネント内の最初のブレークポイントで停止させます。Browse to the Fetch Data page to hit the first breakpoint in the FetchData component just before it issues an HTTP request to the server.
  4. F5 キーを押して実行を続け、サーバーの WeatherForecastController 内のブレークポイントで停止させます。Press F5 to continue execution and then hit the breakpoint on the server in the WeatherForecastController.
  5. F5 キーをもう一度押して実行を続け、天気予報テーブルがブラウザーにレンダリングされることを確認します。Press F5 again to let execution continue and see the weather forecast table rendered in the browser.

注意

デバッグ プロキシが実行状態になる前のアプリの起動中には、ブレークポイントで停止することはありませんBreakpoints are not hit during app startup before the debug proxy is running. これには、Program.Main (Program.cs) のブレークポイントと、アプリから要求された最初のページによって読み込まれるコンポーネントの OnInitialized{Async} メソッドのブレークポイントが含まれます。This includes breakpoints in Program.Main (Program.cs) and breakpoints in the OnInitialized{Async} methods of components that are loaded by the first page requested from the app.

アプリが / 以外のアプリ ベース パスでホストされている場合、Properties/launchSettings.json で次のプロパティを更新し、アプリのベース パスを反映させます。If the app is hosted at a different app base path than /, update the following properties in Properties/launchSettings.json to reflect the app's base path:

  • applicationUrl:applicationUrl:

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

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

前の設定のプレースホルダー:The placeholders in the preceding settings:

  • {INSECURE PORT}:セキュリティで保護されていないポート。{INSECURE PORT}: The insecure port. 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。A random value is provided by default, but a custom port is permitted.
  • {APP BASE PATH}:アプリのベース パス。{APP BASE PATH}: The app's base path.
  • {SECURE PORT}:セキュリティで保護されているポート。{SECURE PORT}: The secure port. 既定では、ランダムな値が提供されますが、カスタム ポートが許可されます。A random value is provided by default, but a custom port is permitted.
  • {PROFILE 1, 2, ... N}:起動設定プロファイル。{PROFILE 1, 2, ... N}: Launch settings profiles. 通常、既定では、1 つのアプリから複数のプロファイルが指定されます (たとえば、IIS Express 用のプロファイルと、Kestrel サーバーで使用されるプロジェクト プロファイル)。Usually, an app specifies more than one profile by default (for example, a profile for IIS Express and a project profile, which is used by Kestrel server).

次の例では、アプリは /OAT でホストされており、アプリ ベース パスは <base href="/OAT/"> として wwwroot/index.html に構成されています。In the following examples, the app is hosted at /OAT with an app base path configured in wwwroot/index.html as <base href="/OAT/">:

"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 のホストと展開」を参照してください。For information on using a custom app base path for Blazor WebAssembly apps, see ASP.NET Core Blazor のホストと展開.

ブラウザーでデバッグするDebug in the browser

このセクションのガイダンスは、Windows で実行されている Google Chrome と Microsoft Edge に適用されます。The guidance in this section applies to Google Chrome and Microsoft Edge running on Windows.

  1. 開発環境でアプリのデバッグ ビルドを実行します。Run a Debug build of the app in the Development environment.

  2. ブラウザーを起動し、アプリの URL (https://localhost:5001 など) に移動します。Launch a browser and navigate to the app's URL (for example, https://localhost:5001).

  3. ブラウザーで Shift + Alt + D キーを押すことにより、リモート デバッグの開始を試みます。In the browser, attempt to commence remote debugging by pressing Shift+Alt+d.

    ブラウザーはリモート デバッグが有効で実行されている必要があります。これは既定ではありません。The browser must be running with remote debugging enabled, which isn't the default. リモート デバッグが無効になっている場合、"デバッグ可能なブラウザー タブが見つからない" というエラー ページと、デバッグ ポートを開いた状態でブラウザーを起動する手順がレンダリングされます。If remote debugging is disabled, an Unable to find debuggable browser tab error page is rendered with instructions for launching the browser with the debugging port open. ブラウザーの指示に従って、新しいブラウザー ウィンドウを開きます。Follow the instructions for your browser, which opens a new browser window. 前のブラウザー ウィンドウを閉じます。Close the previous browser window.

  1. リモート デバッグが有効な状態でブラウザーが実行されていると、前のステップのデバッグ キーボード ショートカットにより、新しいデバッガー タブが開きます。Once the browser is running with remote debugging enabled, the debugging keyboard shortcut in the previous step opens a new debugger tab.

  2. 少しすると、 [ソース] タブに、file:// ノード内にあるアプリの .NET アセンブリの一覧が表示されます。After a moment, the Sources tab shows a list of the app's .NET assemblies within the file:// node.

  3. コンポーネント コード (.razor ファイル) と C# コード ファイル (.cs) で、設定したブレークポイントがコードの実行時にヒットします。In component code (.razor files) and C# code files (.cs), breakpoints that you set are hit when code executes. ブレークポイントにヒットした後、コード全体をステップ実行する (F10) か、コードの実行を普通に再開 (F8) します。After a breakpoint is hit, single-step (F10) through the code or resume (F8) code execution normally.

Blazor は、Chrome DevTools プロトコルを実装し、.NET 固有の情報によってプロトコルを拡張するデバッグ プロキシを備えています。Blazor provides a debugging proxy that implements the Chrome DevTools Protocol and augments the protocol with .NET-specific information. デバッグ用のキーボード ショートカットが押されると、Blazor はプロキシで Chrome DevTools を指し示します。When debugging keyboard shortcut is pressed, Blazor points the Chrome DevTools at the proxy. プロキシは、デバッグしようとしているブラウザー ウィンドウに接続します (そのためリモート デバッグを有効にする必要があります)。The proxy connects to the browser window you're seeking to debug (hence the need to enable remote debugging).

ブラウザー ソース マップBrowser source maps

ブラウザー ソース マップを使用すると、ブラウザーのコンパイルされたファイルを元のソース ファイルにマップし直すことができ、これはクライアント側のデバッグによく使用されます。Browser source maps allow the browser to map compiled files back to their original source files and are commonly used for client-side debugging. ただし Blazor では現在、C# は JavaScript/WASM に直接マップされません。However, Blazor doesn't currently map C# directly to JavaScript/WASM. その代わり、Blazor はブラウザー内で中間言語の解釈を行うため、ソース マップは関係がありません。Instead, Blazor does IL interpretation within the browser, so source maps aren't relevant.

トラブルシューティングTroubleshoot

エラーが発生している場合は、次のヒントが役立つことがあります。If you're running into errors, the following tips may help:

  • [デバッガー] タブで、ブラウザー内の開発者ツールを開きます。In the Debugger tab, open the developer tools in your browser. コンソールで localStorage.clear() を実行して、任意のブレークポイントを削除します。In the console, execute localStorage.clear() to remove any breakpoints.
  • ASP.NET Core HTTPS 開発証明書がインストールされ、信頼されていることを確認します。Confirm that you've installed and trusted the ASP.NET Core HTTPS development certificate. 詳細については、「ASP.NET Core に HTTPS を適用する」を参照してください。For more information, see ASP.NET Core に HTTPS を適用する.
  • Visual Studio では、 [ツール] > [オプション] > [デバッグ] > [全般][Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE)] (ASP.NET (Chrome、Edge、IE) の JavaScript デバッグを有効にする) オプションをオンにする必要があります。Visual Studio requires the Enable JavaScript debugging for ASP.NET (Chrome, Edge and IE) option in Tools > Options > Debugging > General. これは、Visual Studio の既定の設定です。This is the default setting for Visual Studio. デバッグが機能していない場合は、オプションがオンになっていることを確認します。If debugging isn't working, confirm that the option is selected.
  • ご利用の環境で HTTP プロキシを使用している場合は、プロキシ バイパス設定に localhost が含まれていることを確認してください。If your environment uses an HTTP proxy, make sure that localhost is included in the proxy bypass settings. これを行うには、次のいずれかに NO_PROXY 環境変数を設定します。This can be done by setting the NO_PROXY environment variable in either:
    • プロジェクトの launchSettings.json ファイル。The launchSettings.json file for the project.
    • すべてのアプリに適用する場合は、ユーザーまたはシステム環境変数レベルで。At the user or system environment variables level for it to apply to all apps. 環境変数を使用する場合は、Visual Studio を再起動して変更を有効にしてください。When using an environment variable, restart Visual Studio for the change to take effect.

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

Blazor フレームワークのデバッグ プロキシは、起動に少し時間がかかります。そのため、OnInitialized{Async} ライフサイクル メソッド内のブレークポイントにヒットしない可能性があります。The Blazor framework's debugging proxy takes a short time to launch, so breakpoints in the OnInitialized{Async} lifecycle method might not be hit. デバッグ プロキシが起動してブレークポイントにヒットするまでの時間を確保するために、メソッド本体の開始に対して遅延を追加することをお勧めします。We recommend adding a delay at the start of the method body to give the debug proxy some time to launch before the breakpoint is hit. if コンパイラ ディレクティブに基づいて遅延を含めると、アプリのリリース ビルドに対しては遅延が存在しないようにすることができます。You can include the delay based on an if compiler directive to ensure that the delay isn't present for a release build of the app.

OnInitialized:OnInitialized:

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

    ...
}

OnInitializedAsync:OnInitializedAsync:

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

    ...
}

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

Visual Studio で、タイムアウトに達したことを示すデバッグ アダプターの起動失敗の例外がスローされた場合、レジストリ設定でタイムアウトを調整できます。If Visual Studio throws an exception that the debug adapter failed to launch mentioning that the timeout was reached, you can adjust the timeout with a Registry setting:

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

上記のコマンドの {TIMEOUT} プレースホルダーはミリ秒単位です。The {TIMEOUT} placeholder in the preceding command is in milliseconds. たとえば、1 分は 60000 として割り当てられます。For example, one minute is assigned as 60000.