DTPab

DTPにまつわるあれこれ

ESDebugger for VSCode v2.0.2がリリースされました🎉

はじめに

Visual Studio Code(以下、VS Code)の拡張機能であるExtendScript Debugger for Visual Studio Code(以下、ESDebugger)の新しいバージョンv2.0.2(以下、V2)が先日リリースされましたね。これによって大きく仕様変更され、使い勝手が大きく変わりました。
こういった開発ツール系のアップデートは(Adobeのアプリケーションのリリースノート等に比べれば)大したアナウンスもなく粛々と重ねられていくものです。
これからVS Codeとともに生きていくしかない(僕は生涯Macユーザーと心に誓った)ので、新しい情報をキャッチアップできるように、自分から能動的にアクションしないといけないですね。

さて、今回の記事はESDebugger V2について、ExtendScriptの開発・デバッグに焦点を置いて、その使い方を解説します*1。まだ詳細にテストしきれていない部分もあるので、間違っているところ、補足などがあればぜひご連絡ください。

本記事の情報源

この記事を書くに当たり、ESDebuggerのOverviewを参照しながらテストしました。

当初、抄訳を作る予定でしたが、あまりにボリュームがあるため見送りました。
詳細は原文を参照してください。

諸注意

以下の件、冒頭に書かれている警告です。僕自身は未検証なので、テストされた方は情報いただけると助かります。

VS Codeのネイティブビルドでは動作しませんが、Rosettaを使用するIntel/Universalビルドでは動作します。拡張機能を使用する方法については、以下の既知の問題を参照してください。

V2による変更点の概要

V2になって全面的に変わったのですが、具体的に何が変わったのかを少し細かく仕分けてみるとこのようになります。

  • インターフェース
  • launch.jsonのオプション
  • 操作方法

全面的に変わったの意味が伝わるでしょうかw

インターフェース

V1では、スクリプトを動作させる対象アプリケーション(以下、ホスト・アプリケーション)がステータスバー(フッター)に表示されていました。これがなくなっています

ご覧のように、これまでデバッグ対象アプリが表示されていたところに何もなくなり、左側に▷がついたボタンが現れています(画像では「Eval in Adobe...」ボタン)。

一方、launch.jsonが存在しデバッグセッションが登録されていると、前回使ったデバッグセッションが表示されるようになります。
ステータスバーの使い方については後述します。

launch.json

launch.jsonの設定如何で使い勝手が大きく変わるのはV1と同じです。
先に変更点を記し、具体的なlaunch.jsonの書き方は後述します。

変更になったプロパティ

V2で変更になったプロパティは以下の通りです。これらのプロパティを利用していた場合、V2用に書き換えないと無視されます。

V1 V2
targetSpecifier hostAppSpecifier
program script
excludes hiddenTypes

変数ビューに表示/非表示させる項目のコントロール

V1では、excludesプロパティに指定できる項目は4つほどでした。
V2(hiddenTypesプロパティ)ではより細かく、以下の項目を指定できます。

  • "undefined"
  • "null"
  • "boolean"
  • "number"
  • "string"
  • "object"
  • "this"
  • "prototype"
  • "builtin"
  • "Function"

指定したタイプの変数は、変数ビューに表示されなくなります。ご自身の変数ビューの使い勝手と相談しながら調整してみてください。

起動モード

V2になって大きく使い勝手が変わる可能性があるのが起動モードです。
attachlaunchという2種類の起動モード*2をはっきり使い分けられるようになりました。

attachリクエスト

VS Codeでデバッグセッションが開始されますが、スクリプトファイル自体の評価は開始しません。VS Codeをデバッグできる状態で待機させます。今回のアップデートの肝と言っていいでしょう。
この状態で、以下の2つを満たすスクリプトを実行すると、VS Codeでデバッグ情報をキャッチできるようになります。

  1. 指定したホスト・アプリケーションと同じアプリケーション
  2. 指定したターゲットエンジンで動作するスクリプト

ここでいう「スクリプトの実行」は、VS Codeからスクリプトを実行(評価)するケースはもちろん、ホスト・アプリケーションのスクリプトパネルからスクリプトを実行するケースも含みます。

例えば、デバッグセッションをattachでスタートさせ、ホスト・アプリケーションindesign-17.064(InDesign 2022)、ターゲットエンジンmainを指定したとします。
デバッグセッションを開始した状態で、ホスト・アプリケーションであるInDesign 2022のスクリプトパネルから、ターゲットエンジンの指定がない(ないしmainを指定した)スクリプトを実行させてみましょう。
スクリプトに$.writeln()メソッドがあれば(ホスト・アプリケーションからのスクリプトの実行であるにも関わらず)、VS Codeのデバッグコンソールに情報が書き込まれます。

このattachリクエストは、ScriptUIのpalettewindowを使ったスクリプト、またCEPの内部スクリプトのデバッグにおいて非常に有用です。
例えば、ScriptUIのフローティングウィンドウを生成するpaletteを使ったスクリプトは、V1ではフローティングウィンドウを生成し終えた時点でデバッグセッションが終了してしまうため、中身のスクリプトのデバッグには工夫が必要でした。
V2では(attachリクエストでデバッグセッションを開始しておけば)、ホスト・アプリケーション側からフローティングウィンドウを操作した結果を、デバッグ情報としてVS Codeで受け取ることが可能になったわけです。

また、attachリクエストがしっかり実装されたことでマルチターゲットデバッグも可能になりました*3

launchリクエスト

V1までの使い方と同様の感覚で使えるのがlaunchリクエストです。
attachリクエストと異なり、デバッグセッションの開始と同時にスクリプトが実行(評価)されます。
launchリクエストの場合、launch.jsonには下記のオプションが追加で利用できます。

プロパティ 備考 初期値
script string ホスト・アプリケーションでデバッグするスクリプトの絶対パス。指定しない場合、VS Codeでアクティブなコンテンツが実行されます。V1のprogramプロパティ。 ""
bringToFront boolean デバッグセッション開始と同時にホスト・アプリケーションをアクティブにするかどうか。 false
debugLevel number デバッグレベル:
  • 0 - デバッグなし
  • 1 - ブレークポイント、エラー、例外処理でスクリプトを一時停止
  • 2 - 実行可能な最初の行でスクリプトを一時停止
1

実行させるスクリプトファイルの指定がなくてもVS Codeでアクティブなものがデバッグ対象になるという点で、V1と比べるとユーザーフレンドリーな仕様になりました。

launch.jsonの生成

もしワークスペース内にlaunch.jsonファイルがなければ、実行とデバッグビューから作成することができます。

  1. launch.jsonを生成するワークスペースの作成
  2. laucnh.jsonのタイプ:ExtendScriptを選択
  3. launch.jsonが生成され、エディターに表示されます

以下はこの方法で生成される、デフォルトとも言えるlaunch.jsonです。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "extendscript-debug",
            "request": "attach",
            "name": "Attach to ExtendScript Engine"
        },
        {
            "type": "extendscript-debug",
            "request": "launch",
            "name": "Launch Script in ExtendScript Engine"
        }
    ]
}

nameプロパティに「attach」か「launch」かを明記しておくとどちらのリクエストでデバッグセッションが起動されるか分かりやすいのでオススメです。

サンプルケース

はじめはlaunch.jsonの設定をどうすべきか悩ましいかもしれません。
2つのサンプルケースを紹介しますので、お好みに合わせて使いながら調整してみてください。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "extendscript-debug",
            "request": "launch",
            "name": "Launch Script in InDesign 2022",
            "hostAppSpecifier": "indesign-17.064",
            "engineName": "main"
        }
    ]
}

標準的なlaunchリクエストの設定です。
hostAppSpecifierプロパティにホスト・アプリケーション、engineNameプロパティにターゲットエンジンを記述します。InDesignの場合は"main"を指定するとデフォルトエンジンで起動できます*4
アプリケーションを指定する必要がありますが、V1までのデバッグ開始の感覚と近いと思います。

ただ、launchリクエストならショートカットキーに登録することができます(後述)ので、わざわざlaunchリクエストの設定を作る必要はないかもしれません。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "extendscript-debug",
            "request": "attach",
            "name": "Attach to InDesign 2022",
            "hostAppSpecifier": "indesign-17.064",
            "engineName": "session"
        }
    ]
}

こちらは、ターゲットエンジンにデフォルトエンジン以外を指定したattachリクエストです。
ScriptUIで実装したフローティングウィンドウを用いたスクリプトや、CEPの内部スクリプトのデバッグに有用です。
ターゲットエンジン名はそれらのスクリプトと共通のエンジン名にしてください。
もしエンジン名を指定せず、都度使い分けたい場合はengineNameプロパティを削除してください。

操作方法

V1では、F5キーを押してデバッグセッションを開始し、スクリプトをホスト・アプリケーションで実行させることができました。
もちろんV2でも同じです。
ですが、前述のようにV2でlaunch.jsonの設定項目に大きく変更が加えられたため、V1の頃のlaunch.jsonのままだとうまく実行できないかもしれません。
また、launch.jsonに記述しないとホスト・アプリケーションとターゲットエンジンを都度指定するようになっています。
このとき、ホスト・アプリケーションが立ち上がっていないとエラーになってしまいますので、スクリプトを動作させるホスト・アプリケーションは事前に起動しておく必要があります

launch.jsonなしでデバッグを実行する

V1同様V2でも、launch.jsonがなくてもデバッグを開始できます。

  1. 実行とデバッグビューから「実行とデバッグ」ボタンを押す
  2. 起動モード(attach or launch)を選択
  3. ホスト・アプリケーションを選択
  4. ターゲットエンジンを選択

という手順でスクリプトを実行できます(上記はあくまで一例です)。
単にスクリプトを実行させるだけなら、起動モードはlaunchでいいでしょう。

コマンドを利用する

launch.jsonの有無に関わらず、以下のコマンドでデバッグセッションを開始できます。

  • 「Evaluate Script in Host...」コマンドを実行する(launchリクエストによる起動)
  • 「Evaluate Script in Attached Host...」コマンドを実行する(attachリクエストによる起動)

独自ショートカットキーによるデバッグ実行

デバッグ実行コマンドに任意のショートカットキーを設定できるようになりました*5
しかも、下記の引数を持たせることができます。

引数 備考 初期値
"hostAppSpecifier" string ホスト・アプリケーション。指定しないと都度ダイアログから選びます。 ""
"engineName" string ターゲットエンジン。指定しないと都度ダイアログから選びます。 ""
"script" string デバッグするスクリプトファイルへの絶対パス。指定しないとエディタでアクティブなファイルが対象になります。 ""
"bringToFront" boolean デバッグ開始後にホスト・アプリケーションを前面にする(アクティブにする)かどうか。 false
"debugLevel" number デバッグレベル:
  • 0 - デバッグなし
  • 1 - ブレークポイント、エラー、例外処理でスクリプトを一時停止
  • 2 - 実行可能な最初の行でスクリプトを一時停止
1
"registeredSpecifier" string InDesign Serverで利用する特殊なものらしいです。詳細は割愛。 ""

ショートカットキーが増えてしまいますが、ホスト・アプリケーションやターゲットエンジンなどを分けて登録しておけば、逐一ダイアログから選ぶ手間が省けて便利に使えます。
具体的な設定方法は記事を改めますが、興味がある方はESDebuggerのOverviewとVS Codeのショートカットキー設定を参照してください。

ステータスバー操作

V2になり、ステータスバー(フッター)には2つの新しいボタンが追加されました*6

Eval in Adobe...ボタン

js、jsx、jsxbinファイルを開いていると表示され、クリックすると「Evaluate Script in Host...」コマンドを実行します。
ホスト・アプリケーション、ターゲットエンジンを選択すると、開いているファイルがスクリプトとして実行(評価)されます。

既にデバッグセッションが開始されている(attachリクエストで起動している)場合、ホスト・アプリケーション名とターゲットエンジン名が末尾に表示されます。

Halt in Adobe...ボタン

このボタンはVS Codeからスクリプトが実行(評価)されたときに表示され、クリックするとスクリプトの実行(評価)を停止します。
起動中のデバッグセッションが一つの場合、そのホスト・アプリケーションとターゲットエンジン名が末尾に表示されます。

複数のデバッグセッションが起動されている場合、クリックすると起動中のデバッグセッションがリスト表示され、その中から停止させるデバッグセッションを選択することができます。

その他の注意事項

  • 複数のVS Codeウィンドウから、同じホスト・アプリケーションに同時に接続することはできません。最後に接続したものだけが機能します。
  • アクティブなデバッグセッションなしに「Evaluate Script in Host...」コマンドが実行された際、エラーが出てその行がハイライトされ、処理が止まることがあります。このハイライト表示は下記の方法でリセットできます。
    • 別のファイルをアクティブにする
    • ファイルを閉じ、再び開く
    • 別のスクリプトファイルを実行(評価)する
    • デバッグセッションを開始する
    • 関連するエラーメッセージを閉じるか、ステータスバー右側のベルのマークをクリックする(VS Codeの設定によってどちらかになります)
    • 「Clear Error Highlights...」コマンドを実行する
  • ESDebuggerは#target#targetengineプリプロセッサディレクティブを無視します。launch.jsonで設定されたホスト・アプリケーションとターゲットエンジン、ないしデバッグを開始した際に動的に選択される設定を常に参照します。
  • デバッグセッションから切断する場合:
    • ホストエンジンはすべてのVS Codeブレークポイントの登録を解除し、スクリプトの評価を続行するよう指示されます。
    • その後、スクリプト内にdebugger$.bp()などが記述されていればそこでホストエンジンが一時停止し、デバッガーからの通信を待機します。評価プロセスを停止するか、attachリクエストでデバッグセッションを手動で接続することができます。

さいごに

コンパクトにまとめようにも限界がある内容で、なかなか長くて読みづらくなってしまいました。
とりあえず、理解さえしてしまえば何も難しいことはありません。いろいろ試してみて、自分なりに使いやすい設定を探してみてください。

マルチターゲットデバッグとキーボードショートカットキーの設定については、後日また記事を書こうと思っています。
また、それらの内容も踏まえてもう少し図を加えてわかりやすくした同人誌の改訂版も出したいなぁなどと甘いことを考えていますが、果たしてどうなるやら…。

ひとまず、最後までお付き合いいただきありがとうございました。
この記事がESDebugger V2の道標になれば幸いです。

*1:実際にはCEPやイベントのコールバックについてもデバッグしやすくなっているようです

*2:VS Codeの用語として正確にいうと、このattachとlaunchのことを「デバッグセッションリクエスト」といいます

*3:マルチターゲットデバッグについては記事を改めたいと思います

*4:アプリケーションによってデフォルトエンジン名は異なります

*5:ショートカットキーで起動できるのはlaunchリクエストのみです

*6:非表示になることもあるので常時2つ見えているわけではないです