HoloLens2実機上で動作するアプリに対してVisualStudioのUnityデバッガーでスクリプトデバッグを行う

本日は HoloLens の技術調査枠です。
HoloLens2 実機上で動作するアプリに対して VisualStudio の Unity デバッガーでスクリプトデバッグを行う手順を記事にします。

Unity を使用したマネージデバッグ

Unity プロジェクトで所定の設定を行うことで HoloLens 2 上で動作する IL2CPP UWP アプリに対して Unity デバッガーを利用できます。
docs.microsoft.com

サンプルシーンの作成

デバッグを実施する自作のサンプルアプリを作成してみます。

サンプルスクリプト

以下のような HoloLens2 上(UWP時のみ)で動作するコードを含むサンプルスクリプトを用意しました。
IncNumber 関数を実行すると動作環境に応じて異なる変数がインクリメントされます。
・TestScript.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    /// <summary>
    /// Unityエディター上でのインクリメント値
    /// </summary>
    private int Number = 0;

    /// <summary>
    /// HoloLens2上でのインクリメント値
    /// </summary>
    private int UWPNumber = 0;

    /// <summary>
    /// インクリメント実行
    /// </summary>
    public void IncNumber()
    {
#if WINDOWS_UWP
        // HoloLens2(UWP)時の実行コード
        UWPNumber++;
#else
        // Unityエディター時の実行コード
        Number++;
#endif
    }
}

ボタンオブジェクトをシーンに配置し、ボタンをタップしたときに IncNumber 関数が呼ばれるようにしました。

Unityエディター上でのスクリプトデバッグ

まずは Unity エディター上でスクリプトデバッグを実施してみます。
[再生]ボタンを押してシーンを再生します。

スクリプトデバッグを実施したいスクリプトファイルを開きます。
VisualStudio が開いたら[Unity にアタッチ]を実行してスクリプトデバッグを開始します。

[準備完了]が表示されたら、スクリプトデバッグが開始しています。
デバッグ動作を確認するため、インクリメントの実行コードの左行をクリックしてブレークポイントを設定します。

この状態で Unity エディターに戻り、シーン上でボタンをタップしてみます。

ブレークポイントのコードが実行され、処理が一時的に中断します。
マウスオーバーでコードが実行される直前の変数の状態が確認できます。

シーンを再開したい場合は VisualStudio の[続行]ボタンをクリックします。

Unity エディターに戻り、再びシーン上のボタンをタップすると、変数が正常にインクリメントされていることが確認できます。

これで Unity エディター上でのスクリプトデバッグを確認できました。
シーンを停止してデバッグを終了します。

Tips

MRTK のシミュレータを用いた Unity エディター上でのシーンの操作方法の詳細は以下を参照ください。
bluebirdofoz.hatenablog.com

Unityプロジェクトの設定と環境設定

HoloLens2 上で動作するアプリケーションを Unity デバッガーにアタッチするため、幾つかの設定を行います。

UnityプロジェクトのCapability設定

アプリケーションにネットワークの利用許可を設定します。
メニューから[Edit -> Project Settings]を開き、[Player -> Publishing Settings]パネルを開きます。

以下の2つの Capability にチェックを入れて有効にします。
・InternetClientServer
・PrivateNetworkClientServer

Unityデバッガーを実行するPCのネットワーク環境設定

Unity デバッガーを実行する PC は HoloLens2 と同一のネットワーク上に配置されており、かつ、そのネットワーク環境でマルチキャストがサポートされている必要があります。
コントロールパネルからファイアウォールの[詳細設定]を確認します。

利用のネットワーク環境で VisualStudio の UDP 通信が許可されていることを確認します。

特定の環境下で動作するコードのアセンブリ参照を追加

本項目の作業は特定の環境下で動作するコードのスクリプトデバッグを行いたい場合にのみ必要です。
今回はサンプルコードでの #if WINDOWS_UWP の部分のコードをデバッグするため、指定プラットフォームのアセンブリ参照を追加します。

指定プラットフォームのアセンブリ参照の追加手順は以下の記事を参照して実施してください。
bluebirdofoz.hatenablog.com

本手順を実行すると、左上のプルダウンからアセンブリ参照を切り替えることができます。
これでプラットフォーム依存のコードのデバッグが可能になります。

プロジェクトのビルドとインストール

Unity プロジェクトのビルドと HoloLens2 へのインストールを実行します。

Unityプロジェクトのビルド設定

メニューから[Edit -> Build Settings]を開きます。

設定欄から以下の2つの項目にチェックを入れて有効化し、[Build]を実行します。
・Development Build
・Script Debugging

Unity ビルドで作成された VisualStudio のソリューションファイルを開きます。

ソリューションの Package.appxmanifest ファイルを開き、[機能]タブを確認します。
[機能]欄の以下の項目がチェックされていることを確認します。
・インターネット(クライアントとサーバー)
・プライベートネットワーク（クライアントとサーバー)

構成を[Debug]に指定してビルドし、HoloLens2 にアプリケーションをインストールします。
今回はメニューから[デバッグ -> デバッグ無しで開始]で HoloLens2 にアプリケーションをインストールしました。

スクリプトデバッグはアプリ起動後に接続を行うものなので、インストール時に自動起動したアプリケーションは閉じて問題ありません。

HoloLens2上でのスクリプトデバッグの実行

HoloLens2 にインストールしたアプリケーションのスクリプトデバッグを実施します。

HoloLens2側のアプリケーション起動

初めに、HoloLens2 がスクリプトデバッグを行う PC と同じネットワークに接続されていることを確認します。
また、このとき HoloLens2 が PC にUSB接続されていない必要があります。
これは USB 接続を行うと Windows IP Over USB により IP アドレスが割り当てられてしまうためです。

アプリ一覧からインストールを行ったアプリケーションを起動します。

HoloLens2 でアプリケーションが起動し、ボタンが表示されました。

次に PC 側の作業に戻り、スクリプトデバッグの接続を行います。

Unityデバッガーの接続

スクリプトデバッグを実施したいスクリプトファイルを開きます。
VisualStudio が開いたらメニューから[デバッグ -> Unity デバッガーのアタッチ]を実行します。

[Unityインスタンスの選択]ダイアログが表示されます。
ネットワーク環境設定が正しく行われていれば一覧に、アプリケーションを起動中の HoloLens2 の情報が表示されます。
これを選択し、[OK]ボタンをクリックします。

[準備完了]が表示されたら、HoloLens2 上のアプリケーションのスクリプトデバッグが開始しています。
デバッグ動作を確認するため、インクリメントの実行コードの左行をクリックしてブレークポイントを設定します。
なお、#if WINDOWS_UWP の部分のコードをデバッグするには前述のアセンブリ参照の追加を実施しておく必要があります。

この状態で HoloLens2 の操作に戻り、アプリケーションのボタンをタップしてみます。

ブレークポイントのコードが実行され、HoloLens2 上のアプリケーションが一時的に中断します。
VisualStudio を確認すると、マウスオーバーでコードが実行される直前の変数の状態が確認できます。

シーンを再開したい場合は VisualStudio の[続行]ボタンをクリックします。

HoloLens2 上のアプリケーションの動作が再開されます。
再びボタンをタップしてみます。

再び、ブレークポイントのコードが実行され、HoloLens2 上のアプリケーションが中断します。
変数が正常にインクリメントされていることが確認できました。

これで HoloLens2 実機上のアプリケーションに対してスクリプトデバッグを実施できました。