💻 6月3日の MS Build で開催される VS Code Live に参加しましょう。

デバッグ

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 でのデバッグ」を参照してください。

Debugging using Run and Debug

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

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

以下の3つのオプションがあります。

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

Debugging using Solution Explorer

コマンドパレットによるデバッグ

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

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

Debugging using Command Palette

動的（メモリ内）起動構成によるデバッグ

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

既存の launch.json がある場合

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

Add Dynamic C# Configuration

launch.json がない場合

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

Debug with Show all automatic debug configurations

動的（メモリ内）起動構成の削除

生成された構成は、コマンドパレット ⇧⌘P (Windows, Linux Ctrl+Shift+P) を開き、**Debug: Select and Start Debugging** コマンドを使用することで削除できます。

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

Remove dynamic configuration

エディターのデバッグ/実行ボタンによるデバッグ

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

以下の2つのオプションがあります。

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

Editor Run or Debug

launch.json によるデバッグ

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

プロセスへのアタッチ

C# プロセスへのアタッチは、コマンドパレット ⇧⌘P (Windows, Linux Ctrl+Shift+P) を使用し、**Debug: Attach to a .NET 5+ or .NET Core process** コマンドを実行して行えます。

Attach to a C# process

構成オプション

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

launchSettings.json

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

Debugging using launchSettings.json

詳細については、「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 - Web ブラウザーの起動からの stdout テキストを出力ウィンドウに記録するかどうかを決定するフラグです。デフォルトは true です。
  • csharp.debug.logging.elapsedTiming - true の場合、エンジンログにはリクエストにかかった時間（マイクロ秒単位）を示す adapterElapsedTime および engineElapsedTime プロパティが含まれます。デフォルトは false です。
  • csharp.debug.logging.threadExit - ターゲットプロセス内のスレッドが終了したときにメッセージを記録するかどうかを制御します。デフォルトは false です。
  • csharp.debug.logging.processExit - ターゲットプロセスが終了したとき、またはデバッグが停止したときにメッセージを記録するかどうかを制御します。デフォルトは true です。
  • csharp.debug.suppressJITOptimizations - true の場合、ターゲットプロセスで最適化されたモジュール（リリース構成でコンパイルされた .dll）が読み込まれると、デバッガーは Just-In-Time コンパイラーに対し、最適化を無効にしてコードを生成するよう要求します。詳細情報
  • 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 から設定できます。ホットリロードの動作が予期しないものである場合は、詳細度レベルを上げることをお勧めします。
  • csharp.debug.terminateChildProcesses - デバッグセッション終了時にこれが true に設定されていると、デバッガーはデバッグ対象とそのすべての子プロセスを終了させます。false に設定されていると、デバッグ対象のみが終了し、子プロセスは実行されたままになります。デフォルトは false です。
    • Windows では、子プロセスはジョブオブジェクトを使用して追跡されます。デバッグセッション終了後も存続させる必要のあるプロセスは、CreateProcess を呼び出す際に CREATE_BREAKAWAY_FROM_JOB フラグを渡すことで、これを回避できます。

ブレークポイント

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

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

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

Conditional Breakpoints

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

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

Function Breakpoints

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

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

ログポイントを追加するには、コード行の左端の余白を右クリックします。**ログポイントの追加** を選択し、ログに記録するメッセージを入力します。波括弧（'{' と '}'）で囲まれた式は、ログポイントがヒットしたときに評価されます。

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

トークン 説明 出力例
$FILEPOS 現在のソースファイルの場所 C:\sources\repos\Project\Program.cs:4
$FUNCTION 現在の関数名 Program.<Main>$
$ADDRESS 現在の命令 0x00007FFF83A54001
$TID スレッド ID 20668
$PID プロセス ID 10028
$TNAME スレッド名 <スレッド名なし>
$PNAME プロセス名 C:\sources\repos\Project\bin\Debug\net7.0\console.exe
$CALLER 呼び出し元の関数名 void console.dll!Program.Foo()
$CALLSTACK コールスタック void console.dll!Program.Bar()
void console.dll!Program.Foo()
void console.dll!Program.<Main>$(string[] args)
[外部コード]
$TICK ティック数 (Windows の GetTickCount より) 28194046
$HITCOUNT このブレークポイントがヒットした回数 5

LogMessage Breakpoint

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

トリガーブレークポイントとは、別のブレークポイントがヒットしたときに自動的に有効になるブレークポイントのことです。特定の前提条件を満たした場合にのみ発生するコードの障害ケースを診断する際に非常に役立ちます。

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

例外時の停止

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

Exceptions settings in BREAKPOINTS Run View

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

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

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

例外条件

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

条件の例

条件の値の例 結果
System.NullReferenceException Null 参照例外の場合のみブレークします。
System.NullReferenceException, System.InvalidOperationException Null 参照例外と無効な操作例外の両方でブレークします。
!System.Threading.Tasks.TaskCanceledException タスクキャンセル例外を除くすべての例外でブレークします。
!System.Threading.Tasks.TaskCanceledException, System.NotImplementedException タスクキャンセル例外と未実装例外を除くすべての例外でブレークします。

式の評価

デバッガーでは、デバッグコンソールだけでなく、**ウォッチ** ウィンドウでも式を評価できます。

ホットリロード

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

Hot Reload displayed in the debugging toolbar

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

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

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

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

ランタイムは .NET 8 で Linux/macOS 上のデバッグ中の変更適用に対するサポートを追加したため、これらの OS で実行されている .NET アプリにコード変更を適用するには .NET 8 以降のランタイムバージョンが必要です。

アプリケーションタイプ C# Dev Kit でホットリロードをサポート .NET 8 以降が必要
コンソール ✅ Linux/macOS のみ
テストプロジェクト ✅ Linux/macOS のみ
クラスライブラリプロジェクト ✅ Linux/macOS のみ
ASP.NET Core ⚠️* 現在 .cs ファイルの変更のみサポート Linux/macOS のみ
MAUI ❌* 近日対応予定 --
Unity ❌ --

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

コード変更の適用方法

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

アクション 説明
ホットリロード
Ctrl+Shift+Enter		 コードの変更を適用します（**デバッグツールバー** から利用可能）。
ファイルの保存
⌘S (Windows, Linux Ctrl+S)		 csharp.debug.hotReloadOnSave が true に設定されている場合、コード変更の適用を開始します。詳細については「ユーザー設定」を参照してください。
続行 / ステップオーバー / ステップイン / ステップアウト
F5 / F10 / F11 / ⇧F11 (Windows, Linux Shift+F11)		 ブレーク状態（例：ブレークポイントで停止中）の間に変更が行われた場合、これらのコマンドは自動的に変更を適用します。

Hot Reload demonstrated on ASP.NET

次のステップ

詳細については、以下をお読みください。

  • デバッグ - あらゆる言語のプロジェクトに対して、VS Code でデバッガーを使用する方法を確認します。
6/6/2023
© . This site is unofficial and not affiliated with Microsoft.