Apex 対話型デバッガ

Apex 対話型デバッガ

Apex デバッガを使用すると、顧客が VS Code をクライアントとして使用して、Sandbox 組織やスクラッチ組織の Apex コードをリアルタイムでデバッグできます。このデバッガは次の目的で使用できます。

  • Apex クラスおよびトリガにブレークポイントを設定する。
  • sObject 型、コレクション、Apex システム型などの変数を表示する。
  • Apex データ操作言語 (DML) で有効化されたトリガ、メソッド間のコール、変数などのコールスタックを表示する。
  • インストールされた管理パッケージのグローバルクラス、例外、トリガを操作する(表示されない管理型のオブジェクトを検査する場合は、変数検査ペインにグローバル変数のみが表示されます)。
  • ステップイン、ステップオーバー、ステップアウトなどの標準的なデバッグ操作を行い、ブレークポイントまで実行する。
  • デバッグコンソールに結果を出力する。

登録者の Sandbox 組織をデバッグするには、ISV カスタマーデバッガを使用します。このデバッガは Apex 対話型デバッガ拡張機能に付属します。

Apex デバッガの設定

VS Code で初めて Apex デバッガを使用するときは、次の設定手順を実行します。

  1. デバッグする予定の全種類のスクラッチ組織で、DebugApex 機能をスクラッチ組織定義ファイルに追加します。
    "features": "DebugApex"
  2. VS Code で、[SFDX: Create a Default Scratch Org (SFDX: デフォルトのスクラッチ組織を作成)] を実行します。
  3. DebugApex 機能を含むスクラッチ組織定義ファイルを選択します。
  4. スクラッチ組織の準備ができたら、組織の管理ユーザに Apex デバッガの権限を割り当てます。
    1. VS Code で、[SFDX: Open Default Org (SFDX: デフォルト組織を開く)] を実行します。
    2. ブラウザの [設定] で、[クイック検索] ボックスに「Permission Sets」と入力し、[権限セット] を選択します。
    3. [新規] をクリックします。
    4. 権限セットに覚えやすい名前を付けます (Debug Apex など)。
    5. [この権限セットを使用するユーザ種別の選択] セクションで、[ユーザライセンス] ドロップダウンリストから [なし] を選択します。[なし] を選択すると、権限セットを複数の種別のユーザに割り当てることができます。
    6. 変更内容を保存します。
    7. [システム権限] をクリックします。
    8. [編集] をクリックします。
    9. [Apex のデバッグ] を有効にします。[Apex のデバッグ] に必要な他の権限も自動的に追加されます。
    10. 変更内容を保存します。
    11. [割り当ての管理] をクリックします。
    12. [割り当てを追加] をクリックします。
    13. 権限セットを割り当てるユーザを選択して、[割り当て] をクリックします。
    14. [完了] をクリックします。
  5. 省略可能: VS Code で、[SFDX: Pull Source from Default Scratch Org (SFDX: デフォルトのスクラッチ組織からソースをプル)] を実行します。次に、新しい権限セットをソース制御リポジトリに追加します。Salesforce DX プロジェクトに権限セットのコピーがある場合は、sfdx org:assign:permset -n Your_Perm_Set_Name を実行してスクラッチ組織ユーザに権限を割り当てることができます。
  6. VS Code で、Apex デバッガの起動設定を作成します。
    1. [Debug (デバッグ)] ビューを開くには、VS Code の [Activity Bar (アクティビティバー)] で、バグアイコン (フロート表示テキスト: [Debug (デバッグ)]) をクリックします。
    2. launch.json ファイルを作成するには、ギアアイコン (フロート表示テキスト: [Configure or Fix launch.json (launch.json の設定または修正)]) をクリックして、[Apex Debugger (Apex デバッガ)] を選択します(このファイルをすでに作成している場合は、ギアアイコンをクリックするとファイルが開きます)。
    3. "configurations" 配列内に、"Launch Apex Debugger" 設定を追加します。少なくとも次の情報が必要です。
      "configurations": [
        {
          "name": "Launch Apex Debugger",
          "type": "apex",
          "request": "launch",
          "salesforceProject": "${workspaceRoot}"
        }
      ]
      
    4. launch.json ファイルを保存します。複数のスクラッチ組織で作業する場合でも、各プロジェクトに必要な launch.json ファイルは 1 つのみです。このファイルは、プロジェクトの .vscode ディレクトリに常駐します。

注意: Salesforce の機能と競合する非公式のデバッガ拡張機能が存在します (https://marketplace.visualstudio.com/items?itemName=chuckjonas.apex-debug)。Salesforce の機能を使用中はこの拡張機能を無効にしてください。

コードのデバッグ

やりました! Apex デバッガが設定されました。次は、ブレークポイントを設定してデバッグセッションを開始します。その後、コードをデバッグします。

行ブレークポイントを設定するには、.cls または .trigger ファイルを開き、行番号の左側にある列をクリックします。有効なブレークポイントは赤で表示されます。無効なブレークポイントはグレーで表示されます。[Debug (デバッグ)] ビューの [Breakpoints (ブレークポイント)] パネルにブレークポイントのリストを表示できます。

デバッグセッションを開始するには、[Debug (デバッグ)] ビューの上部にある設定ドロップダウンメニューから、[Launch Apex Debugger (Apex デバッガの起動)] を選択します。次に、緑の再生アイコン (フロート表示テキスト: [Start Debugging (デバッグの開始)]) をクリックします。

デバッグセッションの進行中は、ブレークポイントが設定されたコード行を実行する同期アクティビティがあると、ブレークポイントの時点で実行が停止します。実行が一時停止している間に、コールスタックを調べて変数の現在の値を確認するとよいでしょう。デバッグセッションの進行中にエディタの上部に表示される [Debug (デバッグ)] アクションペインを使用してコードをステップ実行し、値の変化を確認することも考えられます。一度に最大 2 つのスレッドをデバッグできます。詳細は、『Visual Studio Code Docs』の「Debugging (デバッグ)」を参照してください。

例外ブレークポイントの設定

デバッグセッション中に例外が発生した場合に、Apex デバッガの実行を停止するには、例外にブレークポイントを設定します。例外ブレークポイントに達すると、例外の原因となったコード行でデバッガが一時停止します。[Debug (デバッグ)] ビューの [Call Stack (コールスタック)] パネルに、例外の名前が表示されます。

例外ブレークポイントを設定するには、Ctrl+Shift+P キー (Windows、Linux) または Cmd+Shift+P キー (macOS) を押してコマンドパレットを開き、[SFDX: Configure Apex Debug Exceptions (Apex デバッグ: 例外を設定)] を選択します。使用可能な例外のリストに、exceptions in the System namespace と、Exception を拡張するプロジェクトの Apex クラスが表示されます。リストから例外を選択して、[Always break (常に中断)] をクリックします。

例外ブレークポイントを表示するには、[SFDX: Configure Apex Debug Exceptions (Apex デバッグ: 例外を設定)] を実行します。リストの上部に、有効なブレークポイントのある例外クラスが示され、Always break と表示されます。例外ブレークポイントを削除するには、リストから例外を選択して、[Never break (中断しない)] を選択します。

VS Code を閉じると、すべての例外ブレークポイントが削除されます(ただし、行ブレークポイントは維持されます)。

ユーザと要求種別のホワイトリスト登録

デバッグする要求を絞り込むには、launch.json ファイルを編集してホワイトリスト登録を設定します(launch.json ファイルは、プロジェクトの .vscode ディレクトリに常駐します)。ホワイトリスト登録を使用しない場合は、デバッグセッション中、組織のすべてのイベントによってデバッグがトリガされます。ユーザまたは要求種別をホワイトリストに登録すると、デバッグしている問題に関連するイベントのみに着目できます。

"Launch Apex Debugger" 設定に次の検索条件を追加します。

"configurations": [
  {
    "name": "Launch Apex Debugger",
    "type": "apex",
    "request": "launch",
    "salesforceProject": "${workspaceRoot}"
    "userIdFilter": [],
    "requestTypeFilter": [],
    "entryPointFilter": ""
  }
]

"requestTypeFilter" の要求種別候補の値をオートコンプリートするには、Ctrl+スペースキーを押します。

エントリポイントで絞り込むには、正規表現を "entryPointFilter" の値として入力します。たとえば、MyPage Visualforce ページで作成された要求をホワイトリストに登録するには、「".*/apex/MyPage.apexp"」と入力します。

考慮事項

Apex デバッガを使用するときは、次の考慮事項と既知の問題に留意します。

一般的な考慮事項

  • デバッグセッションの進行中に Apex クラスを編集すると、変更内容を保存した後に、ブレークポイントがデバッグの出力と一致しなくなることがあります。

  • デバッグセッションを停止する前に VS Code を閉じると、そのセッションが孤立します。孤立したセッションがある場合は、新しいセッションを開始できません。有効なセッションを停止するには、VS Code で、[SFDX: Stop Apex Debugger Session (SFDX: Apex デバッガセッションを停止)] を実行します。Dev Hub の Apex デバッガセッションを管理するには、[設定] の [Apex デバッガ] に移動します。

  • 評価機能は使用できません。
  • ホットスワップは認められません。次のアクションを行うと、デバッグセッションが強制終了します。
    • パッケージのインストールまたはアンインストール
    • 組織のメタデータを再コンパイルする変更の保存
  • デバッグセッション中に次の項目に対する変更を保存することはできません。
    • Apex クラスまたはトリガ
    • Visualforce ページまたはコンポーネント
    • Lightning リソース
    • 権限または設定
    • カスタム項目またはカスタムオブジェクト

エントリポイントに関する考慮事項

次のエントリポイントはサポートされていません。

  • 非同期に実行されるコード (非同期テストを含む)

    ヒント: startTest メソッドと stopTest メソッドのペアの間にあるコードは同期的に実行できます。非同期機能をデバッグするには、テスト内で次のメソッドを使用します。

  • バッチ Apex、キュー可能 Apex、スケジュール済み Apex
  • 受信メール
  • @future アノテーションのあるコード

ブレークポイントに関する考慮事項

  • 条件付きブレークポイントを設定することはできません。
  • get メソッドまたは set メソッドに設定されたブレークポイントは、そのメソッドのボディ内にある必要があります。
  • ブレークポイントを匿名実行ブロックに設定したり、匿名実行ブロックをステップ実行することはできません。ただし、匿名実行を使用してブレークポイントに達した場合は、スタック内に匿名実行フレームが表示されます。匿名実行コードの変数を表示するには、スタック内のこの行をクリックします。

変数に関する考慮事項

  • 変数を監視することはできません。
  • Visualforce や Lightning の動的コンポーネントの変数検査はサポートされていません。
  • Apex ライブラリオブジェクトのインスタンス変数をドリルインすることはできません。これらのオブジェクトのコンテンツを表示するには、その toString メソッドを使用します。
  • ループ内で宣言された変数は、ループ外にも表示できます。
  • 変数の子の値を確認するには、その変数をドリルインします。たとえば、[SELECT Id, ContactId, Contact.accountId, Contact.Account.ownerId FROM Case] クエリを実行すると、結果が次のようにネストされます。
    Case
    --> Contact
    -----> contactId
    -----> Account
    --------> accountId
    --------> ownerId
    
  • EntityDefinition テーブルから変数に SOQL クエリを実行すると、その変数を明示的に SELECT していなくても、結果に durableId が含まれます。

Feedback or Bugs | Edit this Article