はじめに
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になって大きく使い勝手が変わる可能性があるのが起動モードです。
attach
とlaunch
という2種類の起動モード*2をはっきり使い分けられるようになりました。
attach
リクエスト
VS Codeでデバッグセッションが開始されますが、スクリプトファイル自体の評価は開始しません。VS Codeをデバッグできる状態で待機させます。今回のアップデートの肝と言っていいでしょう。
この状態で、以下の2つを満たすスクリプトを実行すると、VS Codeでデバッグ情報をキャッチできるようになります。
- 指定したホスト・アプリケーションと同じアプリケーション
- 指定したターゲットエンジンで動作するスクリプト
ここでいう「スクリプトの実行」は、VS Codeからスクリプトを実行(評価)するケースはもちろん、ホスト・アプリケーションのスクリプトパネルからスクリプトを実行するケースも含みます。
例えば、デバッグセッションをattach
でスタートさせ、ホスト・アプリケーションindesign-17.064
(InDesign 2022)、ターゲットエンジンmain
を指定したとします。
デバッグセッションを開始した状態で、ホスト・アプリケーションであるInDesign 2022のスクリプトパネルから、ターゲットエンジンの指定がない(ないしmain
を指定した)スクリプトを実行させてみましょう。
スクリプトに$.writeln()
メソッドがあれば(ホスト・アプリケーションからのスクリプトの実行であるにも関わらず)、VS Codeのデバッグコンソールに情報が書き込まれます。
このattach
リクエストは、ScriptUIのpalette
やwindow
を使ったスクリプト、また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 | デバッグレベル:
|
1 |
実行させるスクリプトファイルの指定がなくてもVS Codeでアクティブなものがデバッグ対象になるという点で、V1と比べるとユーザーフレンドリーな仕様になりました。
launch.jsonの生成
もしワークスペース内にlaunch.jsonファイルがなければ、実行とデバッグビューから作成することができます。
- launch.jsonを生成するワークスペースの作成
- laucnh.jsonのタイプ:ExtendScriptを選択
- 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がなくてもデバッグを開始できます。
- 実行とデバッグビューから「実行とデバッグ」ボタンを押す
- 起動モード(
attach
orlaunch
)を選択 - ホスト・アプリケーションを選択
- ターゲットエンジンを選択
という手順でスクリプトを実行できます(上記はあくまで一例です)。
単にスクリプトを実行させるだけなら、起動モードは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 | デバッグレベル:
|
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の道標になれば幸いです。