デバッグ

Visual Studio Code で C# アプリケーションをデバッグするには、Microsoft C# 拡張機能を使用します。

実行とデバッグ

C# 拡張機能は、C# Dev Kit と共に、C# アプリケーションを実行およびデバッグするための複数の方法を提供します。

C# Dev Kit なしで実行およびデバッグするには、ドキュメントについてMicrosoft C# 拡張機能の GitHub ページを参照してください。

F5 でデバッグ

C# Dev Kit 拡張機能がインストールされており、デバッグビューで選択できるデバッグ構成がない場合、.cs ファイルを開いて F5 キーを押すことでプロジェクトのデバッグを開始できます。デバッガーは自動的にプロジェクトを見つけてデバッグを開始します。複数のプロジェクトがある場合は、どのプロジェクトのデバッグを開始するかを尋ねられます。

VS Code のサイドバーにある実行とデバッグビューからデバッグセッションを開始することもできます。詳細については、VS Code でのデバッグを参照してください。

ソリューションエクスプローラーでデバッグ

C# Dev Kit 拡張機能がインストールされている場合、ソリューションエクスプローラーでプロジェクトを右クリックするとデバッグコンテキストメニューが表示されます。

オプションは 3 つあります。

• 新しいインスタンスを開始 - デバッガーがアタッチされた状態でプロジェクトを開始します。
• デバッグなしで開始 - デバッガーがアタッチされていない状態でプロジェクトを実行します。
• 新しいインスタンスにステップイン - デバッガーがアタッチされた状態でプロジェクトを開始しますが、コードのエントリポイントで停止します。

コマンドパレットでデバッグ

C# Dev Kit 拡張機能がインストールされている場合、コマンドパレット ⇧⌘P (Windows、Linux では Ctrl+Shift+P) からデバッグ: デバッグの選択と開始コマンドを使用してデバッグを開始することもできます。

注: これにより、デバッグドロップダウンリストに起動構成エントリが追加されます。

動的 (インメモリ) 起動構成でデバッグ

C# Dev Kit 拡張機能がインストールされている場合、動的起動構成を作成できます。作成方法は、プロジェクトに既存の launch.json ファイルがあるかどうかによって異なります。

既存の launch.json

既存の launch.json がある場合、デバッグビューに移動し、ドロップダウンを選択して、C# オプションを選択できます。これにより、ドロップダウンリストに追加できる起動ターゲットの選択肢が表示されます。選択後、F5 を押すか、新しく生成された構成でデバッグの開始をクリックできます。

launch.json がない場合

プロジェクトに launch.json がない場合、デバッグビューのすべての自動デバッグ構成を表示でこれらの動的構成を追加およびアクセスできます。

動的 (インメモリ) 起動構成の削除

生成された構成は、コマンドパレット ⇧⌘P (Windows、Linux では Ctrl+Shift+P) を使用し、デバッグ: デバッグの選択と開始コマンドで削除できます。

ドロップダウンには、既存のすべてのデバッグ構成がリストされます。動的構成の上にマウスを置くと、右側にクリック可能なゴミ箱アイコンが表示されます。そのアイコンを選択して動的構成を削除できます。

エディターのデバッグ/実行ボタンでデバッグ

エディターで .cs ファイルを開いている場合、エディターウィンドウの右上隅にあるボタンから実行およびデバッグオプションにアクセスできます。これらのアクションは、現在のファイルを使用してプロジェクトシステムを照会し、起動する関連プロジェクトを決定します。

2 つのオプションは次のとおりです。

• このファイルに関連付けられたプロジェクトを実行: これは、noDebug: true でデバッグアダプターを使用してプログラムを起動します。
• このファイルに関連付けられたプロジェクトをデバッグ: これは、デバッガーの下でプログラムを起動します。

launch.json でデバッグ

C# Dev Kit を使用している場合、このオプションを使用しないことをお勧めします。ただし、デバッグ構成を直接変更する必要がある場合は、「C# デバッグのための launch.json の構成」を参照してください。

Attaching to a process

コマンドパレット ⇧⌘P (Windows、Linux では Ctrl+Shift+P) を使用し、デバッグ: .NET 5+ または .NET Core プロセスにアタッチコマンドを実行することで、C# プロセスにアタッチできます。

Configuration options

デバッガーを構成するために多くのオプションと設定が利用可能です。launchSettings.json、VS Code のユーザー設定を使用してデバッグオプションを変更したり、直接 launch.json を変更したりできます。

launchSettings.json

Visual Studio から launchSettings.json を持っている場合、F5 から実行またはコマンドパレットから実行を使用してプロファイルがリストされているはずです。

詳細については、「C# デバッグの構成」を参照してください。

ユーザー設定

C# デバッガーを使用中に変更したい設定がある場合、これらのオプションはファイル > 基本設定 > 設定 (⌘, (Windows、Linux では Ctrl+,)) で検索することで見つけることができます。

• csharp.debug.stopAtEntry - true の場合、デバッガーはターゲットのエントリポイントで停止する必要があります。このオプションのデフォルトは false です。
• csharp.debug.console - コンソールプロジェクトを起動する場合、ターゲットプログラムを起動するコンソールを示します。注: このオプションは「dotnet」デバッグ構成タイプでのみ使用されます。
  • internalConsole [既定] - VS Code のデバッグコンソール。このモードでは、デバッガーとターゲットプログラムの両方からのメッセージを 1 か所で確認できます。詳細については、完全なドキュメントを参照してください。
  • integratedTerminal - VS Code の統合ターミナル。
  • externalTerminal - ユーザー設定で構成できる外部ターミナル。
• csharp.debug.sourceFileMap - ビルド時のパスをローカルソースの場所にマップします。ビルド時のパスのすべてのインスタンスは、ローカルソースパスに置き換えられます。
    例
      {"<ビルドパス>":"<ローカルソースパス>"}
• csharp.debug.justMyCode - 有効な場合 (既定)、デバッガーはユーザーコード (「マイ コード」) のみを表示し、ステップインします。システムコードや最適化されたコード、またはデバッグシンボルを持たないコードは無視されます。詳細情報。
• csharp.debug.requireExactSource - 現在のソースコードが PDB と一致する必要があることを示すフラグ。このオプションのデフォルトは true です。
• csharp.debug.enableStepFiltering - プロパティと演算子をステップオーバーできるようにするフラグ。このオプションのデフォルトは true です。
• csharp.debug.logging.exceptions - 例外メッセージをアウトプットウィンドウにログ出力するかどうかを決定するフラグ。このオプションのデフォルトは true です。
• csharp.debug.logging.moduleLoad - モジュールロードイベントをアウトプットウィンドウにログ出力するかどうかを決定するフラグ。このオプションのデフォルトは true です。
• csharp.debug.logging.programOutput - 外部コンソールを使用しない場合、プログラムの出力をアウトプットウィンドウにログ出力するかどうかを決定するフラグ。このオプションのデフォルトは true です。
• csharp.debug.logging.diagnosticsLog - デバッガーの問題を診断するために使用されるさまざまな設定。
• csharp.debug.logging.browserStdOut - ウェブブラウザの起動からの標準出力テキストをアウトプットウィンドウにログ出力するかどうかを決定するフラグ。このオプションのデフォルトは true です。
• csharp.debug.logging.elapsedTiming - true の場合、エンジンログには、リクエストにかかった時間 (マイクロ秒単位) を示す adapterElapsedTime および engineElapsedTime プロパティが含まれます。このオプションのデフォルトは false です。
• csharp.debug.logging.threadExit - ターゲットプロセス内のスレッドが終了したときにメッセージがログに記録されるかどうかを制御します。このオプションのデフォルトは false です。
• csharp.debug.logging.processExit - ターゲットプロセスが終了したとき、またはデバッグが停止したときにメッセージがログに記録されるかどうかを制御します。このオプションのデフォルトは true です。
• csharp.debug.suppressJITOptimizations - true の場合、最適化されたモジュール (リリース構成でコンパイルされた .dll) がターゲットプロセスにロードされると、デバッガーはジャストインタイムコンパイラに最適化を無効にしたコードを生成するように要求します。詳細情報
• csharp.debug.symbolOptions.searchPaths - .pdb ファイルを検索するシンボルサーバー URL の配列 (例: http://MyExampleSymbolServer) またはディレクトリ (例: /build/symbols)。これらのディレクトリは、モジュールの横の既定の場所と、PDB が元々配置されていたパスに加えて検索されます。
• csharp.debug.symbolOptions.searchMicrosoftSymbolServer - true の場合、Microsoft シンボルサーバー (https://msdl.microsoft.com/download/symbols) がシンボル検索パスに追加されます。指定されていない場合、このオプションのデフォルトは false です。
• csharp.debug.symbolOptions.searchNuGetOrgSymbolServer - true の場合、NuGet.org シンボルサーバー (https://symbols.nuget.org/download/symbols) がシンボル検索パスに追加されます。指定されていない場合、このオプションのデフォルトは false です。
• csharp.debug.symbolOptions.cachePath - シンボルサーバーからダウンロードされたシンボルをキャッシュするディレクトリ。指定されていない場合、Windows ではデバッガーは %TEMP%\\SymbolCache に、Linux および macOS ではデバッガーは ~/.dotnet/symbolcache にデフォルト設定されます。
• csharp.debug.symbolOptions.moduleFilter.mode - モジュールフィルターが動作する2つの基本動作モードのどちらかを制御します。
  • loadAllButExcluded - モジュールが excludedModules 配列にない限り、すべてのモジュールのシンボルをロードします。
  • loadOnlyIncluded - includedModules 配列にあるか、includeSymbolsNextToModules 設定を通じて含まれている場合を除き、どのモジュールについてもシンボルをロードしようとしません。
• csharp.debug.symbolOptions.moduleFilter.excludedModules - デバッガーがシンボルをロードすべきではないモジュールの配列。ワイルドカード (例: MyCompany.*.dll) がサポートされています。このプロパティは、mode が loadAllButExcluded に設定されていない限り無視されます。
• csharp.debug.symbolOptions.moduleFilter.includedModules - デバッガーがシンボルをロードすべきモジュールの配列。ワイルドカード (例: MyCompany.*.dll) がサポートされています。このプロパティは、mode が loadOnlyIncluded に設定されていない限り無視されます。
• csharp.debug.symbolOptions.moduleFilter.includeSymbolsNextToModules - true の場合、includedModules 配列にないモジュールについては、デバッガーはモジュール自体と起動実行可能ファイルの隣をチェックしますが、シンボル検索リスト上のパスはチェックしません。このオプションのデフォルトは true です。このプロパティは、mode が loadOnlyIncluded に設定されていない限り無視されます。
• csharp.debug.allowFastEvaluate - true (既定の状態) の場合、デバッガーは単純なプロパティとメソッドの実行をシミュレートすることで、より高速な評価を試みます。
• csharp.experimental.debug.hotReload - true の場合、ターゲットアプリケーションがホットリロードをサポートしていれば、デバッガーはデバッグ中に変更を適用できるようにします。
• csharp.debug.hotReloadOnSave - true (既定の状態) の場合、デバッガーはファイルが保存されると自動的にコード変更を適用します。
• csharp.debug.hotReloadVerbosity - C# ホットリロード出力ウィンドウのログの詳細度を制御します。minimal (既定)、detailed、または diagnostic に設定できます。ホットリロードが予期せぬ動作を開始した場合は、詳細度レベルを上げることをお勧めします。

Breakpoints

C# デバッガーは、ソース行ブレークポイント、条件付きブレークポイント、ログポイントなど、さまざまなブレークポイントをサポートしています。

ブレークポイント - 条件付きブレークポイント

式の評価を利用して、デバッガーは条件付きブレークポイントもサポートします。式が true と評価されたときにブレークするようにブレークポイントを設定できます。

ブレークポイント - 関数ブレークポイント

デバッガーは関数ブレークポイントもサポートします。デバッグペインのブレークポイントセクションにある + をクリックすることで、特定の関数でブレークするようにブレークポイントを設定できます。

ブレークポイント - ログポイント

ログポイント (Visual Studio ではトレースポイントとも呼ばれます) を使用すると、コードを編集せずにデバッグコンソールに出力を送信できます。これらは、アプリケーションの実行フローを停止しないため、ブレークポイントとは異なります。

ログポイントを追加するには、コード行の左端のマージンを右クリックします。ログポイントの追加を選択し、ログに記録したいメッセージを入力します。波括弧 ('{' と '}') の間の式は、ログポイントに到達したときに評価されます。

ログメッセージでは以下のトークンもサポートされています。

ブレークポイント - トリガーされたブレークポイント

トリガーされたブレークポイントとは、別のブレークポイントに到達すると自動的に有効になるブレークポイントです。これらは、特定の事前条件の後にのみ発生するコードの失敗ケースを診断する際に非常に役立ちます。

トリガーされたブレークポイントは、グリフマージンを右クリックし、トリガーされたブレークポイントの追加を選択し、その後、どの他のブレークポイントがこのブレークポイントを有効にするかを選択することで設定できます。

Stopping on exceptions

C# デバッガーは、例外がスローまたはキャッチされたときにデバッガーが停止するための構成オプションをサポートしています。これは、実行ビューのブレークポイントセクションにある 2 つの異なるエントリを通じて行われます。

注: フォルダが C# デバッガーで初めてデバッグされるまで、ブレークポイントセクションにはこれらのエントリが表示されません。

すべての例外をチェックすると、例外がスローされたときにデバッガーが停止するように構成されます。ジャストマイコードが有効になっている場合 (デフォルトで有効)、例外がライブラリコード内で内部的にスローされてキャッチされた場合はデバッガーはブレークしません。ただし、例外がライブラリコードでスローされ、ユーザーコードに返された場合、デバッガーはブレークします。

ユーザー未処理の例外をチェックすると、ユーザーコードでスローされた後、またはユーザーコードを経由して非ユーザーコードでキャッチされたときにデバッガーが停止するように構成されます。ユーザー未処理になった例外は、デバッグ中のプロセスにおける常にバグであるとは限りません。ユーザーコードが API を実装しており、例外を発生させることが期待されている場合もあります。多くの場合、実際の問題があるため、デフォルトでは、例外がユーザー未処理になったときにデバッガーは停止します。

例外条件

両方のチェックボックスは、選択した例外タイプのみでブレークする条件をサポートします。条件を編集するには、鉛筆アイコン (上記の画像参照) を選択するか、エントリを右クリックして条件の編集を呼び出します。条件は、ブレークする例外タイプのカンマ区切りのリストです。リストが「!」で始まる場合、無視する例外タイプのリストになります。

条件の例

Expression evaluation

デバッガーは、ウォッチウィンドウとデバッグコンソールの両方で式を評価することもできます。

Hot Reload

C# Dev Kit 拡張機能がインストールされている場合、デバッガーはデバッグ中に C# コードの変更を適用できます。

ホットリロードを有効にするには、csharp.experimental.debug.hotReload を true に設定する必要があります。詳細については「ユーザー設定」を参照してください。ホットリロードセッションは、ターゲットデバッガーエンジンがコード変更の適用をサポートしている場合にのみ開始されます。

サポートされているプロジェクトとシナリオ

C# Dev Kit は、「編集と続行」としても知られる「クラシック」ホットリロード体験をサポートしています。ブレークポイントで停止しているかプログラムが実行中かに関わらず、デバッグ中にコード変更を適用できます。

2023 年 11 月現在、変更後、ASP.NET Core アプリケーションがブラウザを自動的に更新できるようにする MetadataUpdateHandler などの一部の機能は、まだ利用できません。デバッグなしでのコード変更の適用もサポートされていません。

.NET 8 で Linux/macOS 上でのデバッグ中の変更適用がランタイムに追加されたため、これらのOS上で動作する.NETアプリにコード変更を適用する場合は、.NET 8+ のランタイムバージョンが必要です。

C# Dev Kit で現在サポートされているプロジェクトの詳細については、「サポートされているプロジェクト」を参照してください。その他のサポートされていないシナリオのトラブルシューティングの詳細については、「C# Dev Kit FAQ」も参照してください。

コード変更の適用方法

ホットリロードセッションが開始され、新しい変更が行われると、以下のいずれかのアクションでこれらの変更をアプリケーションに適用できます。

次のステップ

さらに読む

• デバッグ - VS Code で任意の言語のプロジェクトでデバッガーを使用する方法を確認します。