Version: 2021.2
言語: 日本語
統合開発環境 (IDE) サポート
ユニットテスト

Unity での C# コードのデバッグ

デバッガーを使用すると、アプリケーションやゲームの実行中にソースコードを検査することができます。Unity は、以下のコードエディターを使用して C# コードのデバッグをサポートします。

  • Visual Studio (Visual Studio Tools for Unity プラグインを使用)

  • Visual Studio for Mac

  • Jetbrains Rider

  • Visual Studio Code

これらのコードエディターは、サポートするデバッガー機能がわずかに異なりますが、すべてがブレークポイント、シングルステップ、変数検査などの基本的な機能を提供します。

Unity のマネージコードデバッグは WebGL を除くすべてのプラットフォームで使用できます。Mono と IL2CPP 両方のスクリプティングバックエンドで動作します。

コードエディターの設定

Visual Studio (Windows)

Unity エディターのインストーラーには、Visual Studio Tools for Unity プラグインといっしょに Visual Studio をインストールするためオプションが含まれています。これは Unity を使ったデバッグ用に Visual Studio を設定する推奨される方法です。

Visual Studio が既にコンピューターにインストールされている場合は、Tools > Get Tools and Features… メニューを使用して、Visual Studio Tools for Unity プラグインを見つけてインストールします。

Visual Studio for Mac

Unity エディターのインストーラーには、Visual Studio for Mac をインストールするためオプションが含まれています。これは Unity を使ったデバッグ用に Visual Studio for Mac を設定する推奨される方法です。

Visual Studio for Mac が既にコンピューターにインストールされている場合は、Extension Manager を使用して、Visual Studio Tools for Unity プラグインを見つけてインストールします。

JetBrains Rider

JetBrains Rider のデフォルトのインストールでは、Windows または Mac で Unity のコードをデバッグできます。インストールするには JetBrains ウェブサイト を参照してください。

VS Code

VS Code を使用するには、Unity でコードをデバッグするために拡張機能をインストールする必要があります。インストールするには、こちらの拡張機能の 説明 に従ってください。

Unity での外部スクリプトエディターの指定

Once you’ve installed a code editor, go to Preferences > External Tools and set the External Script Editor to your chosen code editor.

エディターでのデバッグ

Unity エディターが再生モードになっている間に、Unity エディターで実行されている C# コードをデバッグすることができます。

エディターでデバッグを行うには、エディターのコード最適化モードを デバッグモード に設定し、デバッグ機能を持つコードエディターを設定する必要があります。

コード最適化モードを変更するには、Unity Editor Status Bar の右にあるデバッグボタンを選択します。

Unity エディターのステータスバーの右下にあるデバッグボタン
Unity エディターのステータスバーの右下にあるデバッグボタン

Unity のコード最適化設定には 2 つのモードがあります。

  • Debug Mode - 外部のデバッガーソフトを接続して使用することができますが、エディタのプレイモードでプロジェクトを実行すると、C#のパフォーマンスが低下します。
  • Release Mode - エディターの再生モードでプロジェクトを実行すると、C# のパフォーマンスが速くなりますが、外部のデバッガーを取り付けることはできません。

ステータスバーのデバッグボタンをクリックすると、小さなポップアップウィンドウが開き、モードを切り替えるためのボタンが表示されます。また、現在のモードに関する情報や、モードを切り替えた場合の動作についても表示されます。

デバッグモードポップアップでは、現在のモードが表示され、モードを切り替えることができ、モードを切り替えた場合の動作についても説明されています。
デバッグモードポップアップでは、現在のモードが表示され、モードを切り替えることができ、モードを切り替えた場合の動作についても説明されています。

To change which mode the Unity Editor starts up in, go to Edit > Preferences > General > Code Optimization On Startup.

Preferences では、Unity の起動時のコード最適化モードを変更することができます。
Preferences では、Unity の起動時のコード最適化モードを変更することができます。

スクリプトを通してこれらの設定を制御するには、次の API を使用します: ManagedDebuggerCompilation.CompilationPipeline-codeOptimizationCompilation.CodeOptimization

また、エディターの起動モードを変更したり、デバッガーのリッスンソケットをオフにすることもできます。これを行うには、エディターを起動する際に、以下の コマンドライン引数 を使用します。

  • -releaseCodeOptimization エディターを Release コード最適化モードで起動します。
  • -debugCodeOptimization エディタを Debug コード最適化モードで起動します。
  • -disableManagedDebugger デバッガーのリスンソケットを無効にして、エディターを起動します。

ブレークポイントの設定とエディターへの設定

まず、外部コードエディターで、デバッガーを停止するスクリプトコードの行のブレークポイントを設定します。Visual Studio では、例えば、コードの左側の列で、デバッガーを停止したい行をクリックします (下図参照)。行番号の横に赤い円が表示され、行がハイライト表示されます。

Visual Studio で設定されたブレークポイント
Visual Studio で設定されたブレークポイント

次に、コードエディターを Unity エディターに設定します (Attach to Unity)。このオプションはコードエディターによって異なり、コードエディターの通常のデバッグ処理とオプションが異なる場合があります。Visual Studio では、オプションは以下のようになります。

Visual Studio の Attach To Unity ボタン
Visual Studio の Attach To Unity ボタン

コードエディターの中には、デバッグする Unity のインスタンスを選択できるものがあります。例えば、Visual Studio の Debug> Attach Unity Debugger オプションを使用すると、この機能が使用可能になります。

デバッグに利用できる Unity の現在のインスタンスを表示する Visual Studio。この例では、エディターで動作するインスタンスが 1 つ、Android Plyaer として動作しているインスタンスが 1 つあります。
デバッグに利用できる Unity の現在のインスタンスを表示する Visual Studio。この例では、エディターで動作するインスタンスが 1 つ、Android Plyaer として動作しているインスタンスが 1 つあります。

コードエディターを Unity エディターに設定したら、Unity エディターに戻って再生モードを開始します。ブレークポイントのコードが実行されると、デバッガーは停止します。例えば以下のようになります。

ブレークポイントで停止している Visual Studio のデバッガー
ブレークポイントで停止している Visual Studio のデバッガー

コードエディターがブレークポイントにある間、変数の内容を段階的に見ることができます。デバッガーで継続 (continue) オプションを選択するか、デバッグモードを停止するまで、Unity エディターは応答しません。

プレイヤーでのデバッグ

Unity プレイヤー で実行中のスクリプトコードをデバッグするには、プレイヤーをビルドする前に、Development Build と Script Debugging オプションを有効にしてください (これらのオプションは File> Build Settings にあります)。Wait For Managed Debugger オプションを有効にすると、スクリプトコードが実行される前に、デバッガーがプレイヤーにアタッチされるのをプレイヤーが待機させることができます。

コードエディターを Unity プレイヤーにアタッチするには、プレイヤーの IP アドレス (またはマシン名) とポートを選択します。 Visual Studioでは、Attach To Unity オプションのドロップダウンメニューは以下のようになります。

Debug > Attach Unity Debugger オプションは以下のようになります。

デバッガーをプレイヤーにアタッチし、Unity エディターにアタッチしないように注意してください (両方が実行されている場合)。デバッガーをアタッチしたら、通常のデバッグを続行できます。

Android と iOS デバイスのデバッグ

Android

Android デバイスで実行中にプレイヤーをデバッグする場合は、USB または TCP 経由でデバイスに接続します。例えば、Visual Studio (Windows) で Android デバイスに接続するには、Debug > Attach Unity Debugger を選択します。 プレイヤーインスタンスを実行しているデバイスのリストが表示されます。

この場合、携帯機器は Unity エディターと Visual Studio を実行するワークステーションの USB か同じネットワーク上の Wi-Fi を通して接続されます。

Chrome OS の Android

Unity では Chrome OS デバイスを自動検出できません。接続を開始するには、IP アドレスによって Android Debug Bridge (adb) を通してデバイスに接続してから、デバッガーダイアログで IP アドレスを手動で入力します。

iOS

iOS デバイスで実行されているプレイヤーをデバッグする場合は、TCP 経由でデバイスに接続します。たとえば、Visual Studio (Mac) で iOS デバイスに接続するには、Debug > Attach Unity Debugger オプションを選択します。プレイヤーインスタンスを実行しているデバイスのリストが表示されます。

デバイスが 1 つのアクティブなネットワークインターフェースのみを持ち (Wi-Fi が推奨なのでモバイルデータ通信をオフにします)、IDE とデバイスの間のファイアウォールが TCP ポートをブロックしていないことを確認します (上記のスクリーンショットでポート番号 56000)。USB 経由のデバッグは iOS ではサポートされていません。

デバッガーのトラブルシューティング

デバッガーのほとんどの問題は、コードエディターが Unity エディターやプレイヤーを見つけることができないために発生します。つまり、デバッガーを正しく設定できないということです。デバッガーはエディターまたはプレイヤーへの TCP 接続を使用するため、接続の問題はしばしばネットワークによって発生します。以下は、基本的な接続問題のトラブルシューティングを行うための手順です。

デバッガーを正しい Unity インスタンスに設定するよう確認する

コードエディターは、デバッグが有効になっているローカルネットワーク上のすべての Unity エディターまたは Unity プレイヤーに設定することができます。デバッガーを設定する場合は、正しいインスタンスにアタッチしていることを確認します。Unity プレイヤーを実行しているデバイスの IP アドレスやマシン名が分かっている場合は、正しいインスタンスを見つけるのに役立ちます。

Unity インスタンスへのネットワーク接続を確認する

コードエディターは、Unity プロファイラーが使用するのと同様のメカニズムを使用して、デバッグする Unity インスタンスを見つけます。コードエディターが Unity インスタンスを見つけることができない場合は、Unity プロファイラーをそのインスタンスに接続してみてください。Unity プロファイラーもそれを見つけることができない場合は、コードエディター、または Unity インスタンス (または両方) を実行しているマシンにファイアウォールが存在する可能性があります。ファイアウォールがある場合は、以下の ファイアウォール設定について を参照してください。

デバイスがアクティブなネットワークインターフェースを 1 つしか持たないように確認する

多くのデバイスは複数のネットワークインターフェースを持っています。例えば、携帯電話はアクティブなモバイル通信接続とアクティブな Wi-Fi 接続の両方がある場合があります。デバッガーを TCP に正しく接続するには、IDE がデバイスの正しいインターフェースにネットワーク接続する必要があります。Wi-Fi 経由でデバッグする場合は、デバイスを機内モードにして他のすべてのインターフェースを無効にしてから、Wi-Fi を有効にしてください。

Unity プレイヤーが IDE に指示する IP アドレスは、プレイヤーログで確認することができます。次のようなログの一部を見てください。


Multi-casting "[IP] 10.0.1.152 [Port] 55000 [Flags] 3 [Guid] 2575380029 [EditorId] 4264788666 [Version] 1048832 [Id] iPhonePlayer(Joshs-iPhone):56000 [Debug] 1 [PackageName] iPhonePlayer" to [225.0.0.222:54997]...

このメッセージは、IDE が IP アドレス 10.0.1.152 とポート 56000 を使用してデバイスに接続しようとしていることを示しています。この IP アドレスとポートは、IDE を実行しているコンピューターからアクセス可能である必要があります。

ファイアウォールの設定を確認する

Unity インスタンスは、TCP 接続を通してコードエディターと通信します。ほとんどの Unity プラットフォームでは、この TCP 接続は任意に選択されたポートで行われます。通常、このポートはコードエディターが自動的に検出する必要があるため、ポートを認識する必要はありません。それでもうまくいかない場合は、ネットワーク分析ツールを使用して、コードエディターを実行しているマシンや、Unity インスタンスを実行しているマシンやデバイスのうち、どのポートがブロックされているかを判断してください。ポートが見つかったら、ファイアウォールが、コードエディターを実行しているマシンのポートと Unity インスタンスを実行しているマシンの両方にアクセスできることを確認します。

マネージデバッグ情報が有効であることを確認する

デバッガーがアタッチしても、ブレークポイントがロードされない場合は、デバッガーがコードのマネージデバッグ情報を見つけることができない可能性があります。マネージコードのデバッグ情報は、ディスク上のマネージアセンブリ (.dllファイル) の隣の .pdb という名前のファイルに格納されます。

正しい設定とビルドオプションが有効になっている場合 (上記参照)、Unity はこのデバッグ情報を自動的に生成します。ただし、Unity はプロジェクトのマネージプラグインのデバッグ情報を生成できません。関連する .pdb がある場合、マネージプラグインからコードをデバッグことが可能です。ファイルは Unity プロジェクトのマネージプラグインの隣にあります。

デバイスがロックされないようにする

アプリケーションをデバッグするために使用しているデバイスに画面ロックがある場合は、これが無効になっていることを確認してください。画面ロックはデバッガーが切断される原因となり、再接続を妨げます。マネージコードのデバッグ中に画面がロックされないように気をつけてください。画面がロックされている場合は、デバッガーが再度接続する前に、デバイス上でアプリケーションを再起動する必要があります。

  • 2018–09–06 公開ページ

  • マネージコードのデバッグは 2018.2 で追加

統合開発環境 (IDE) サポート
ユニットテスト