Implementazione del debug snapshot
Uno scenario di supporto comune per i consulenti è quando vengono contattati dal cliente per la presenza di un problema nella soluzione per cui è necessario eseguire la risoluzione dei problemi al fine di determinare la causa e la posizione dell'inconveniente nel codice.
Sebbene siano disponibili il supporto per la creazione di sandbox con una copia dei dati di produzione e il debug/l'arresto del flusso del programma senza alcun impatto sul tenant di produzione di un cliente, in alcuni casi il cliente viene bloccato e il consulente è sotto pressione per indagare e risolvere il problema senza avere il tempo necessario per effettuare il provisioning di un ambiente duplicato in cui riprodurre il problema.
Per far fronte a questa situazione, Microsoft ha introdotto la possibilità di collegare il debugger AL di Visual Studio Code a un tenant di produzione per scattare snapshot dell'esecuzione del codice, consentendo una rapida indagine e collaborazione con il cliente sui passaggi esatti di riproduzione.
Con la nuova funzione snapshot è possibile:
Impostare punti di acquisizione snapshot nel codice.
Creare una nuova configurazione di collegamento snapshot. Potrebbe trattarsi di client Web, API Web o sessione in background (specificando l'ID utente o l'ID sessione; non esiste ancora alcuna interfaccia utente di selezione).
Eseguire il collegamento a un ambiente in modalità snapshot.
Eseguire i passaggi di riproduzione per attivare i punti di acquisizione snapshot.
Scaricare il punto di acquisizione snapshot in Visual Studio Code dopo aver completato la riproduzione.
Controllare l'analisi dello stack/l'esecuzione del programma, nonché le variabili nei punti di acquisizione snapshot offline in Visual Studio Code.
Il debug snapshot consente a un amministratore con delega di registrare il codice AL che viene eseguito sul server e, una volta eseguito, eseguire il debug dello snapshot registrato in Visual Studio Code. Affinché un amministratore con delega possa creare e scaricare un file snapshot che esiste sul server per conto di un utente finale, l'amministratore con delega deve far parte del gruppo di autorizzazioni Debug snapshot D365.
Uno dei vantaggi del debug snapshot è che offre la possibilità di controllare l'esecuzione del codice e le variabili nell'ambiente di produzione in un servizio cloud, in una sessione utente specificata.
Il debug snapshot introduce il concetto di punti di acquisizione snapshot. Un punto di acquisizione snapshot è un punto di interruzione in Visual Studio Code che viene impostato quando si crea uno snapshot, che non arresta, tuttavia, l'esecuzione del codice come avviene invece quando si usa il debug regolare. I punti di acquisizione snapshot indicano all'esecuzione di registrare lo stato nel punto di interruzione per un successivo controllo offline.
Il debug snapshot registrerà il codice AL mentre viene eseguito sul server, ma raccoglierà solo informazioni variabili su:
Punti di acquisizione snapshot
Eccezioni AL
Inizializzazione di una sessione di debug snapshot
Da Visual Studio Code, è possibile avviare uno snapshot creando un file di configurazione apposito.
Sono disponibili due configurazioni di modello per uno snapshot, a cui si accede selezionando Aggiungi configurazione in Visual Studio Code.
AL: inizializza una sessione di debug snapshot in locale
AL: inizializza una sessione di debug snapshot nel cloud
Scegliere se eseguire la sessione in un servizio cloud o in locale.
Il file di configurazione deve contenere le seguenti informazioni:
userId: GUID dell'utente per conto del quale verrà avviato il debug snapshot. Per l'ambiente locale, può essere anche il nome utente negli scenari di autenticazione della password utente. L'utente deve essere in grado di avviare o avere un tipo di sessione aperto specificato nel parametro breakOnNext.
sessionId: ID sessione per l'utente specificato sopra in userId.
snapshotVerbosity: determina la quantità di contesto di esecuzione da registrare. Se è specificato SnapPoint, verranno registrati solo i metodi che selezionano un punto di acquisizione snapshot.
Quando si definisce una configurazione, è possibile inizializzare una sessione di debug snapshot premendo CTRL+MAIUSC+P, quindi selezionando AL:Initialize Snapshot Debugging o premendo F7.
Per registrare l'esecuzione AL, il server attenderà ora che si verifichi una connessione in cui si applicano le seguenti regole:
Se sessionId è specificato per userId per un dato tenant, sarà quella sessione a essere sottoposta a debug snapshot.
Se per un dato tenant è specificato solo userId, sarà la sessione successiva specificata nel parametro di configurazione breakOnNext a essere sottoposta a debug snapshot.
Se non viene specificato alcun userId, la sessione successiva in un dato tenant che convalida il parametro breakOnNext sarà sottoposta a debug snapshot.
Una volta inizializzata una sessione di debug snapshot, il relativo contatore sulla barra di stato verrà aggiornato e avrà l'aspetto seguente:
Stato di una sessione di debug snapshot
Facendo clic sull'icona della barra di stato o premendo MAIUSC+F7 verrà visualizzato un elenco di tutti gli snapshot disponibili.
L'elenco di stato mostra lo stato di una sessione sottoposta a debug snapshot. Una sessione di debug snapshot può trovarsi in uno di questi stati:
Inizializzato: è emessa una richiesta e il server è in attesa che la prossima sessione venga sottoposta a debug snapshot in base alle regole di cui sopra.
Avviato: si è eseguito il collegamento a una sessione dell'utente finale per il debug snapshot.
Completato: visualizzato al termine della sessione di debug snapshot.
Scaricato: visualizzato quando viene scaricato il file snapshot.
Completamento di una sessione di debug snapshot
Una sessione di debug snapshot viene completata premendo ALT+F7. Compariranno tutte le sessioni di snapshot avviate. La scelta di una di queste causa la chiusura del debug della sessione sul server e il download del file snapshot.
Il file snapshot può contenere dati sulla privacy del cliente, pertanto deve essere gestito in conformità alla privacy e deve essere eliminato quando non è più necessario.
È possibile eseguire il debug delle sessioni di debug snapshot che hanno prodotto un file snapshot. Il percorso di un file snapshot è controllato dal parametro di configurazione al.snapshotOutputPath. Per impostazione predefinita è locale nell'area di lavoro corrente ed è denominato ./.snapshots.
Download dei simboli sull'endpoint del debug snapshot
Per scaricare i simboli su un server di produzione, sono necessarie voci correlate alle autorizzazioni:
Essere un amministratore con delega
Disporre inoltre dell'accesso in sola lettura alla tabella delle applicazioni pubblicate enfatizzata nel set di autorizzazioni D365 EXTENSION MGT.
Per il debug è necessario che i simboli sul server corrispondano ai simboli di cui dispone l'utente in locale. In caso contrario, se si imposta un punto di interruzione su una determinata riga in Visual Studio Code, la riga di codice potrebbe differire da quella presente nel server.
Il download dei simboli usa le impostazioni di configurazione di debug snapshotInitialize in Visual Studio Code, che viene configurato quando si sceglie AL: inizializza una sessione di debug snapshot in locale o AL: inizializza una sessione di debug snapshot nel cloud.
{
"name": "snapshotInitialize: MyServer",
"type": "al",
"request": "snapshotInitialize",
"environmentType": "OnPrem",
"server": "http://localhost",
"serverInstance": "BC170",
"authentication": "UserPassword",
"breakOnNext": "WebClient"
},
Per il debug è necessario che i simboli sul server corrispondano ai simboli di cui dispone l'utente in locale. Se questo non è il caso e si imposta un punto di interruzione su una determinata riga in Visual Studio Code, la riga di codice potrebbe differire da quella presente sul server. Questo è il motivo per cui è necessario scaricare i simboli dai server di produzione per il debug snapshot in modo che un punto di interruzione impostato su una riga corrisponda a ciò che il server comprende di questa riga. In questo modo si evita uno scenario in cui si imposta un punto di interruzione in un file DAL sulla riga 12, ma la riga 12 sul server è una riga vuota o diversa se i simboli non sono gli stessi.
Debug di un file snapshot
Due azioni utente possono avviare il debug snapshot.
Creando una nuova configurazione di debug di avvio e specificando il nome del file snapshot nell'impostazione di configurazione snapshotFileName. Questa è l'unica impostazione necessaria oltre al tipo, alla richiesta e al nome.
Facendo clic sull'icona di stato o premendo MAIUSC+F7 e selezionando una sessione sottoposta a debug snapshot terminata.
Dopo che si avvia una sessione di debug snapshot in Visual Studio Code, l'esecuzione del codice si arresta al primo punto di acquisizione snapshot. Le eccezioni AL sono trattate come punti di acquisizione snapshot, con l'unica differenza che non possono essere rimosse dalle azioni utente. Altri punti di acquisizione snapshot sono normali punti di interruzione che è possibile rimuovere o aggiungere nuovamente mediante azioni utente. Se non si specificano punti di acquisizione snapshot per i primi metodi registrati, il punto di interruzione di ingresso sarà la prima riga.
L'utente può impostare punti di interruzione e continuare l'esecuzione fino a tale punto per testare, ad esempio, se si raggiunge una riga, ma è il punto di acquisizione snapshot che contiene le informazioni reali.
AL Profiler
Con AL Profiler per l'estensione AL Language è possibile acquisire un profilo delle prestazioni del codice eseguito per uno snapshot. Usando la visualizzazione dell'editor di profilatura delle prestazioni in Visual Studio Code, è possibile analizzare il tempo impiegato per l'esecuzione tramite viste dello stack di chiamate dall'alto verso il basso e dal basso verso l'alto. AL Profiler funziona su uno snapshot del codice in esecuzione.
Per eseguire la profilatura del codice è necessario innanzi tutto acquisire uno snapshot del codice in esecuzione. La configurazione snapshot include un parametro chiamato executionContext che ha i seguenti valori possibili. Se non si specificano valori, la configurazione predefinita è DebugAndProfile.
Debug: la sessione snapshot non raccoglierà informazioni sul profilo.
Profile: la sessione snapshot raccoglierà solo informazioni sul profilo, i punti di acquisizione snappoint verranno ignorati e il debug non funzionerà.
DebugAndProfile: nella sessione snapshot saranno disponibili sia il debug che la profilatura. Come già indicato, questa è l'impostazione predefinita.
Ciò significa che, per usare lo snapshot sia per scopi di debugging che di profilatura, la configurazione dello snapshot nel file launch.json deve essere come la seguente:
"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"
},
...
Quindi, una volta scaricato il file snapshot, è possibile generare un file del profilo. A tale scopo si può procedere in uno dei due modi seguenti:
Aprire il riquadro comandi usando la scelta rapida da tastiera CTRL+MAIUSC+P, quindi selezionare il comando AL: Genera file profilo e scegliere uno snapshot dal menu a discesa.
In Esplora risorse di Visual Studio Code fare clic con il pulsante destro del mouse sul file snapshot specifico e scegliere Genera file profilo.
Per analizzare il grafico delle chiamate ai metodi, aprire il file del profilo generato nell'editor di profilatura delle prestazioni. Se si seleziona direttamente il file, questo si apre in una vista dall'alto verso il basso. È inoltre possibile fare clic con il pulsante destro del mouse su un file del profilo e ottenere le seguenti opzioni:
Grafico TopDown visualizzatore profili AL
Grafico BottomUp visualizzatore profili AL
Una volta aperto, il file del profilo ha l'aspetto seguente:
Per analizzare i dati mostrati nel grafico è possibile usare diverse modalità di visualizzazione. Per passare da una vista all'altra, è possibile fare clic con il pulsante destro del mouse sul file del profilo e selezionare una vista oppure usare il piccolo pulsante nell'angolo in alto a destra. Il grafico offre due modalità di visualizzazione diverse: dall'alto verso il basso e dal basso verso l'alto.
Quando si ordina lo stack dall'alto verso il basso, il grafico ordina i metodi in base alla sequenza di chiamate, il che significa che i nodi figlio sono i metodi chiamati dal nodo padre. Quando si esegue l'ordinamento dal basso verso l'alto, il grafico viene ordinato come uno stack di chiamate inverso, cioè i nodi figlio sono metodi che hanno chiamato il nodo padre.
Per approfondire l'analisi, le colonne Tempo in metodo e Tempo totale sono indicatori importanti di dove viene speso il tempo nel codice. Tempo in metodo è la quantità di tempo trascorsa solo nel metodo, escluse eventuali chiamate fuori dal metodo. Tempo totale è la quantità di Tempo in metodo più eventuali chiamate fuori dal metodo. Nei grafici dal basso verso l'alto, le colonne Tempo totale e Tempo in metodo sono ordinabili. Fare clic sulle colonne per disporle prima in ordine crescente; fare nuovamente clic su di esse per disporle in ordine decrescente.
Numero di occorrenze è disponibile solo nei grafici dall'alto verso il basso e mostra il numero di volte in cui è stato chiamato un metodo specifico. Il tempo trascorso è aggregato.
È possibile filtrare i nodi nel grafico. La sintassi è la seguente:
@column name | <alias> <op> <value> where
<column name> := [function, url, path, selfTime, totalTime, id, objectType, objectName, declaringApplication]
Gli alias disponibili per i nomi delle colonne sono:
<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>
Visualizzazione delle righe di codice eseguite nell'acquisizione di snapshot
Il debug snapshot è un modo efficace per risolvere i problemi degli ambienti di produzione cloud di Business Central. Poiché le acquisizioni di snapshot non sono interattive, è necessario impostare precedentemente i punti di acquisizione snapshot rendendo il debug snapshot un processo iterativo. Per determinare in modo più efficiente quale codice si è eseguito, ad esempio percorsi di codice condizionali, e permettere di individuare buoni candidati per l'impostazione di nuovi punti di acquisizione snapshot per analizzare lo stato delle variabili per l'esecuzione, si sono aggiunte indicazioni visive alla riproduzione snapshot. Queste indicazioni sono visualizzate come linee verticali nella barra sulla sinistra dell'editor di codice.
Durante la riproduzione snapshot in Visual Studio Code, la barra sulla sinistra dell'editor di codice contiene una barra visiva verticale per indicare quale codice è stato eseguito nell'acquisizione snapshot.
È possibile controllare il colore della barra usando il nuovo elemento al.snapshotDebuggerLinesHitDecoration nel file settings.json.