🚀 VS Code で で入手しましょう!

デバッグ

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) から、[デバッグ: デバッグの選択と開始] コマンドを使用してデバッグを開始することもできます。

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

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) を使用し、[デバッグ: デバッグの選択と開始] コマンドを使用すると、生成された構成を削除できます。

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

Remove dynamic configuration

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

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

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

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

Editor Run or Debug

launch.json によるデバッグ

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

プロセスへのアタッチ

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

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 設定によって含まれている場合を除き、ANY モジュールのシンボルを読み込もうとしません。
  • 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 から設定できます。ホット リロードが予期しない動作を開始した場合は、詳細度レベルを上げることをお勧めします。

ブレークポイント

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 は、編集と続行とも呼ばれる "クラシック" ホット リロード エクスペリエンスをサポートしています。ブレークポイントで停止しているか、プログラムが実行されているかに関係なく、デバッグ中にコード変更を適用できます。

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

ランタイムは、.NET 8 で Linux/macOS でのデバッグ中に変更を適用するためのサポートを追加しました。そのため、これらのオペレーティング システムで実行されている .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