スナップショット デバッグの実装
一般的なサポート シナリオでは、コンサルタントは、原因とコード内の問題の場所を特定するためのトラブルシューティングが必要なソリューションの問題について、顧客から連絡を受けます。
運用データのコピーを含むサンドボックスを作成して、顧客の運用テナントに影響を与えずにプログラム フローをデバッグまたは停止することができますが、いくつかのケースでは顧客がブロックされており、コンサルタントは複製環境をプロビジョニングして問題を再現するための時間が与えられないまま、大きな時間的プレッシャーの下で問題を検証し解決する場合があります。
この問題に対処するために、Microsoft は、Visual Studio Code AL デバッガーを運用テナントに関連付けて、コード実行のスナップショットを取得する機能を提供しています。これにより、問題を正確に再現することができ、顧客と共に素早く問題を検証することができます。
新しいスナップショット機能では、以下を実行することができます。
コード内にスナップポイントを設定する。
新しいスナップショット アタッチ構成を作成する。 これには、Web クライアント、Web API、バックグラウンド セッション (ユーザー ID またはセッション ID を指定して、選択 UI は不可) が含まれます。
スナップショット モードで環境にアタッチする。
スナップポイントをトリガーする手順を再現する。
再現の完了後、スナップポイントを Visual Studio Code にダウンロードする。
Visual Studio Code で、スタック トレース/プログラムの実行、およびオフライン スナップポイントの変数を検査する。
スナップショット デバッグを使用すると、代理管理者は、サーバーで実行される AL コードを記録することができます。コードの実行後、記録したスナップショットを Visual Studio Code でデバッグします。 代理管理者が、エンド ユーザーの代わりにサーバーに存在するスナップショット ファイルを作成しダウンロードするには、代理管理者が D365 スナップショット デバッグ アクセス許可グループに含まれている必要があります。
スナップショット デバッグの利点の 1 つは、指定したユーザー セッションで、運用環境内のコードの実行と変数をクラウド サービス上で検査できる点です。
スナップショット デバッグでは、スナップポイントの概念を使用します。 スナップポイントは、スナップショットが作成される際に設定される Visual Studio Code のブレークポイントですが、通常のデバッグと異なり、コードの実行が停止されることはありません。 スナップポイントによってブレークポイントの状態が記録され、後でオフライン検査を行うことができます。
スナップショット デバッグはサーバー上の AL コード実行を記録しますが、次の変数情報のみを収集します。
スナップポイント
AL 例外
スナップショット デバッグ セッションの初期化
Visual Studio Code から、スナップショット構成ファイルを作成してスナップショットを開始します。
スナップショットには 2 つのテンプレート構成があり、Visual Studio Code で構成の追加を選択することで、この構成にアクセスすることができます。
AL: ローカルでのスナップショット デバッグ セッションの初期化
AL: クラウドでのスナップショット デバッグ セッションの初期化
セッションをクラウド サービスで実行するかローカルで実行するかを選択します。
構成ファイルには、次の情報が含まれている必要があります。
userId - スナップショット デバッグを開始するユーザーの GUID。 オンプレミスでのユーザー パスワード認証のシナリオの場合、ユーザー名を使用することもできます。 ユーザーはセッションを開始できるか、breakOnNext パラメーターで指定されたセッション タイプを開いている必要があります。
sessionId - userId で指定したユーザーのセッション ID。
snapshotVerbosity - 記録する実行コンテキストの量を決定します。 SnapPoint が指定されている場合、そのスナップポイントにヒットするメソッドだけが記録されます。
構成が定義されている場合、Ctrl+Shift+P を押して、AL:Initialize Snapshot Debugging を選択するか、F7 キーを押すことで、スナップショット デバッグ セッションを初期化できます。
AL の実行を記録するため、サーバーは次のルールが適用される接続が実行されるまで待機します。
特定のテナントの userId に sessionId が指定されている場合、スナップショット デバッグはそのセッションで実行されます。
特定のテナントに対して userId だけが指定されている場合、breakOnNext 構成パラメーターで指定された次のセッションでスナップショット デバッグが実行されます。
userId が指定されていない場合、特定のテナントの breakOnNext 構成パラメーターを検証する次のセッションでスナップショット デバッグが実行されます。
スナップショット デバッグ セッションが初期化されると、ステータス バーのスナップショット デバッグ セッション カウンターが更新され、次のように表示されます。
スナップショット デバッグ セッションのステータス
ステータス バー アイコンをクリックするか Shift + F7 キーを押すと、使用可能なすべてのスナップショットの一覧が表示されます。
ステータス リストには、スナップショット デバッグ セッションの状態が表示されます。 スナップショット デバッグ セッションは、次のいずれかの状態になります。
初期化 - 要求が発行され、サーバーは、上記のルールに基づいて、次のセッションでスナップショット デバッグが実行されるのを待機しています。
開始済 - スナップショット デバッグにエンド ユーザー セッションがアタッチされています。
完了 - スナップショット デバッグ セッションが完了しました。
ダウンロード済 - スナップショット ファイルがダウンロードされました。
スナップショット デバッグ セッションの終了
スナップショット デバッグ セッションを終了するには、Alt + F7 キーを押します。 これにより、開始されたすべてのスナップショット セッションが表示されます。 あるセッションを選択すると、サーバーでのデバッグ セッションが閉じ、スナップショット ファイルがダウンロードされます。
スナップショット ファイルには顧客のプライバシー データが含まれているため、プライバシー コンプライアンスに従って処理し、必要がなくなり次第削除する必要があります。
スナップショット ファイルを生成したスナップショット デバッグ セッションはデバッグすることができます。 スナップショット ファイルの場所は、al.snapshotOutputPath 構成パラメーターによって制御されます。 既定では、現在のワークスペースにローカルの ./.snapshots に保存されます。
スナップショット デバッガー エンドポイント シンボルのダウンロード
運用サーバーにシンボルをダウンロードするには、次のエントリに関連するアクセス許可が必要です。
代理管理者であること
D365 EXTENSION MGT アクセス許可セットに示される公開済アプリケーション テーブルへの読み取りアクセスも必要です。
デバッグを行うには、サーバー上のシンボルとユーザーがローカルに持っているシンボルが一致している必要があります。 一致しない場合、Visual Studio Code の特定の行にブレークポイントを設定すると、コード行はサーバー上のものと異なる場合があります。
シンボルのダウンロードは、AL: ローカルでのスナップショット デバッグ セッションの初期化またはAL: クラウドでのスナップショット デバッグ セッションの初期化を選択した際に設定される Visual Studio Code 内の snapshotInitialize デバッグ構成設定を使用します。
{
"name": "snapshotInitialize: MyServer",
"type": "al",
"request": "snapshotInitialize",
"environmentType": "OnPrem",
"server": "http://localhost",
"serverInstance": "BC170",
"authentication": "UserPassword",
"breakOnNext": "WebClient"
},
デバッグを行うには、サーバー上のシンボルとユーザーがローカルに持っているシンボルが一致している必要があります。 一致しない場合、Visual Studio Code の特定の行にブレークポイントを設定すると、コード行はサーバー上のものと異なる場合があります。 これを避けるには、運用サーバーからシンボルをダウンロードしてスナップショット デバッグを実行し、ブレークポイントが設定されている行がサーバー上の行と一致するようにします。 これは、DAL ファイルの 12 行目にブレークポイントを設定したものの、シンボルが異なるためにサーバー上の 12 行目が空白または違う内容になることを避けるためのシナリオです。
スナップショット ファイルのデバッグ
スナップショット デバッグを開始するための 2 つのユーザー アクションが用意されています。
新しい起動デバッグ構成を作成して、snapshotFileName 構成設定でスナップショット ファイル名を指定する。 タイプ、要求、および名前以外に必要な設定は、この設定のみです。
ステータス アイコンをクリックするか Shift + F7 キーを押して、完了したスナップショット デバッグ セッションを選択する。
Visual Studio Code でスナップショット デバッグ セッションが開始されると、コードの実行は最初のスナップポイントで停止します。 ユーザー アクションで削除できないという点を除き、AL 例外はスナップポイントとして扱われます。 他のスナップポイントは、ユーザー アクションによって削除または再追加できる通常のブレークポイントです。 最初に記録されたメソッドでスナップポイントが指定されていない場合、1 行目はエントリ ブレークポイントです。
たとえば、行がヒットし、その行が実際の情報を持つスナップポイントである場合、ユーザーはブレークポイントを設定して、テストの目的でそのブレークポイントまで実行し続けることができます。
AL プロファイラー
AL 言語拡張機能の AL プロファイラーを使用すると、スナップショットに対して実行されたコードのパフォーマンス プロファイルをキャプチャできます。 Visual Studio Code のパフォーマンス プロファイリング エディター ビューを使用すると、トップダウンまたはボトムアップの呼び出しスタック ビューを使用して、実行に費やした時間を調査できます。 AL プロファイラーは、実行されているコードのスナップショットで動作します。
コードのプロファイルを行うには、まず実行されているコードのスナップショットをキャプチャする必要があります。 スナップショット構成には、executionContext というパラメーターがあります。このパラメーターには次の値を設定できます。 何も指定しない場合、構成は既定で DebugAndProfile です。
デバッグ - スナップショット セッションによりプロファイル情報が収集されません。
プロファイル - スナップショット セッションによりプロファイル情報のみ収集されます。スナップポイントは無視され、デバッグは機能しません。
DebugAndProfile - スナップショット セッションの結果としてデバッグとプロファイルの両方を使用できるようになります。 繰り返しになりますが、これが既定値です。
つまり、デバッグとプロファイルの両方の目的でスナップショットを使用する場合、launch.json ファイル内のスナップショットの構成は次の内容と同等になる必要があります。
"configurations": [
{
"name": "snapshotInitialize: Your own server",
"type": "al",
"userId": "555",
"request": "snapshotInitialize",
"environmentType": "OnPrem",
"server": "http://localserver",
"serverInstance": "BC190",
"authentication": "Windows",
"breakOnNext": "WebClient",
"executionContext": "DebugAndProfile"
},
...
次に、スナップショット ファイルをダウンロードすると、プロファイル ファイルを生成できます。 これは、次の 2 つの方法のいずれかで実行できます。
Ctrl + Shift + P ショートカットを使用してコマンド パレットを開き、AL: プロファイル ファイルの生成コマンドを選択して、ドラッグ メニューからスナップショットを選択します。
Visual Studio Code エクスプローラーで、特定のスナップショット ファイルを右クリックし、プロファイル ファイルの生成を選択します。
メソッド呼び出しのグラフを調査するには、パフォーマンス プロファイル エディターで生成されたプロファイル ファイルを開きます。 ファイルを直接クリックすると、トップダウン ビューが表示されます。 プロファイル ファイルを右クリックすると、次のオプションが表示されます。
AL プロファイル ビジュアライザーの TopDown グラフ
AL プロファイル ビジュアライザーの BottomUp グラフ
プロファイル ファイルが開くと、次の図のようになります。
グラフに表示されるデータを調査するには、さまざまな表示モードを使用します。 ビューを切り替えるには、プロファイル ファイルを右クリックしてビューを選択するか、右上隅の小さいボタンを使用します。 グラフには、トップダウンとボトムアップの 2 つの表示モードがあります。
グラフでスタックのトップダウンを並べ替えると、呼び出し順序に従ってメソッドが並べ替えられます。つまり、子ノードは親ノードから呼び出されるメソッドです。 ボトムアップを並べ替えると、グラフは逆呼び出しスタックとして並べ替えられます。つまり、子ノードは親ノードを呼び出したメソッドです。
さらに調査する場合、セルフ時間列と合計時間列が、コードで時間が費やされている場所を示す重要な指標となります。 セルフ時間は、メソッドからの呼び出しを除く、メソッドに費やされた時間です。 合計時間は、セルフ時間にメソッドからの呼び出しを加えた時間です。 ボトムアップ グラフでは、合計時間列とセルフ時間列を並べ替えることができます。 列をクリックすると、まず昇順に並べ替えられ、もう一度クリックすると降順に並べ替えられます。
ヒット数は、トップダウン グラフでのみ使用でき、特定のメソッドが呼び出された回数を示します。 費やされた時間が集計されます。
グラフ内のノードはフィルター処理できます。 構文は次のとおりです。
@column name | <alias> <op> <value> where
<column name> := [function, url, path, selfTime, totalTime, id, objectType, objectName, declaringApplication]
列名に使用できるエイリアスは、次のとおりです。
<alias> := [f, u, p, s, t, id, ot, on, da]
<op> := [numeric operators, boolean operators, string operators]
numeric operators : [:, =, >, <, <=, >=, <>, !=]
: := equal
boolean operators : [:, =, <>, !=]
string operators : [:, =, !=, <>, ~, =]
~ = := <regex>
スナップショットのキャプチャで実行されるコードの行を視覚化する
スナップショット デバッグは、Business Central クラウド運用環境のトラブルシューティングにおける強力な方法です。 スナップショットのキャプチャは非対話型であるため、事前にスナップ ポイントを設定する必要があります。通常、スナップショット デバッグは反復プロセスになります。 条件付きコード パスなど、どのコードが実行されたかを判断する効率を高め、コード実行のための変数の状態を調査する目的で新しいスナップ ポイントを設定するための良い候補を見つけるのに役立つように、スナップショットの再生に視覚的な手掛かりが追加されました。 これらの手掛かりは、コード エディターの左側の余白内の縦のラインとして表示されます。
Visual Studio Code でのスナップショットの再生中に、左側のコード エディターの余白には、スナップショット のキャプチャで実行されたのはどのコードかを示す、垂直の視覚バーが含まれています。
余白バーの色は、settings.json ファイル内の新しい al.snapshotDebuggerLinesHitDecoration を使用して制御できます。