Anatomia di un'estensione di report
Con l'oggetto di estensione report, è possibile estendere gli oggetti del report esistenti, analogamente a come si estendono tabelle e pagine.
Oggetto estensione di report
Con l'oggetto di estensione report, è possibile estendere gli oggetti del report esistenti, analogamente a come si estendono tabelle e pagine. Le estensioni del report consentono di estendere un report esistente tramite le operazioni seguenti:
Aggiunta di colonne a elementi dati esistenti nel set di dati del report
Aggiunta di nuovi elementi dati
Aggiunta di implementazioni di trigger
Aggiunta alle pagine di richiesta
Aggiungere altri layout di report, sia per riflettere i nuovi campi aggiunti con un'estensione, oppure semplicemente aggiungendo nuovi layout di report su un set di dati di report esistente.
Per estendere un report, la proprietà Extensible deve essere impostata su true. Si tratta del valore predefinito, che implica che i report possono essere estesi per impostazione predefinita, a meno che non la proprietà Extensible non sia impostata esplicitamente su false.
Layout di estensione report
Le estensioni dei report possono avere uno o più layout definiti. Per altre informazioni, consultare Definizione di più layout di report. Il layout di un report esistente non può essere esteso, ma è possibile aggiungere nuovi layout. Per usare un report esistente come punto di partenza, è possibile scaricare il layout da Business Central e includerlo nel progetto di estensione.
I layout inclusi in un'estensione del report vengono visualizzati in Business Central come ulteriori layout del report. I layout da un'estensione di report non vengono usati automaticamente quando l'estensione viene distribuita. Per usare uno dei nuovi layout di report, andare alla pagina Layout di report in Business Central, quindi selezionare il layout per il report in questione come nuovo Layout predefinito.
Supporto per frammenti
Se si immette il collegamento treportext viene creato il layout di base per un oggetto estensione di report quando si usa l'estensione per il linguaggio AL in Visual Studio Code.
reportextension Id MyExtension extends MyTargetReport
{
dataset
{
// Add changes to dataitems and columns here
}
requestpage
{
// Add changes to the requestpage here
}
}
Dal client Business Central è possibile esportare i risultati del report come dati non elaborati in un file di Microsoft Excel. Il file contiene tutte le colonne del set di dati, ma senza il layout applicato. Usare il file per verificare che il report restituisca i dati previsti e per assicurare che i controlli del layout del report corrispondano ai tipi di valore del set di dati. Per esportare un set di dati in Excel, eseguire il report e selezionare Invia a > Documento di Microsoft Excel (solo dati) nella pagina di richiesta. Per altre informazioni, consultare Eseguire e stampare report in Business Central.
Limitazioni
Nell'elemento dataset, la sintassi per la modifica dei dati non è supportata, ovvero non è possibile aggiungere nuovi trigger agli elementi di dati esistenti né modificare gli elementi di dati esistenti o le proprietà delle colonne. Nell'elemento requestpage non è possibile modificare alcuna proprietà.
L'uso del trigger OnInitReport non è supportato per le estensioni di report. I trigger OnPreReport e OnPostReport vengono eseguiti dopo i trigger equivalenti del report originale.
Scelta dei layout dalle estensioni di report
Quando un'estensione viene distribuita in un ambiente del cliente, come app Microsoft AppSource o come estensione per tenant (PTE), tutti i layout di report nell'estensione diventano disponibili anche nell'ambiente. Tuttavia, se si desidera applicare un layout di estensione a un report specifico, è necessario aggiungere codice di installazione e aggiornamento nell'estensione.
Gli utenti possono scegliere un layout da un'estensione di report nella pagina Selezione layout report che elenca tutti i layout disponibili per un determinato report. Nella pagina Selezione layout report sono inclusi tutti i layout delle estensioni di report in modo che l'utente possa effettuare una scelta tra tutti i layout disponibili.
Aggiunta di colonne a elementi di dati esistenti
Si consideri uno scenario in cui è necessario aggiungere colonne a un elemento di dati esistente. L'immagine seguente mostra un esempio di come aggiungere colonne a un elemento di dati esistente.
Un nuovo comando add è collegato all'ancoraggio di un elemento di dati. Il comando permette di specificare l'elemento di dati a cui si desidera eseguire un'aggiunta. L'aggiunta può essere eseguita al report di base ma anche agli elementi di dati nelle estensioni di report per quel report di base, il che significa creare una dipendenza sulle altre estensioni di report. È possibile quindi aggiungere colonne all'elemento di dati nonché colonne per i campi nell'origine dell'elemento di dati, incluse le eventuali estensioni presenti per quella origine dell'elemento di dati.
Di conseguenza, se si dispone di una tabella e si desidera creare un report con un'estensione che si basa su una colonna che non si trova nell'origine dati per il report di base, è possibile aggiungerla alla tabella per il report di base tramite un'estensione di tabella, quindi usarla nell'estensione di report.
È anche possibile aggiungere colonne per variabili nell'estensione di report stesso e accedere alle variabili nel report di base, a condizione che siano protette. Attualmente la maggior parte delle variabili nei report di base non sono contrassegnate come protette, ma sono normalmente contrassegnate come private.
Per accedere alle variabili contrassegnate come private nei report di base, è necessario inviare una richiesta per l'applicazione AL su GitHub. Per altre informazioni, vedere Estensione per il linguaggio AL di Visual Studio Code per Dynamics 365 Business Central.
È possibile aggiungere colonne per le espressioni e per le procedure. Le colonne possono essere locali e possono anche trovarsi nel grafo del report, ma anche in questo caso devono essere indicate come protette.
Le colonne hanno le stesse proprietà di un report normale, ad eccezione del fatto che nella versione 2021 ciclo 1 le proprietà Caption, CaptionML e IncludeCaption non sono supportate. Tali proprietà potrebbero essere supportate in un secondo momento.
Modifica di elementi di dati esistenti
La modifica di elementi di dati esistenti in generale non è supportata tramite le estensioni di report. Al momento, non sono previsti piani per supportare la modifica delle proprietà delle colonne. Un'alternativa consiste nell'aggiungere una nuova colonna e nel nascondere le colonne originali dal layout per poi trasformare il valore. Non è previsto il supporto della modifica delle etichette di base né della sostituzione di trigger esistenti. Nelle versioni successive potrà essere presente un maggior supporto per i trigger.
Aggiunta di nuovi elementi di dati agli elementi di dati esistenti
A volte si potrebbe non voler aggiungere a un elemento di dati esistente, aggiungendo piuttosto uno o più nuovi elementi di dati. Questa azione è possibile con Business Central.
Di seguito è riportato un esempio di codice con una nuova sezione per l'aggiunta di elementi di dati.
Per aggiungere un elemento nidificato in un dataitem di destinazione, usare i seguenti valori:
addfirst()
addlast()
Per aggiungere un elemento successivo a un dataitem di destinazione, usare i seguenti valori:
addbefore()
addafter()
In questo esempio è presente un valore addfirst(). È possibile aggiungere elementi di dati al report di base esistente oppure a un'estensione di report nel grafo. I membri sono simili ai normali elementi di dati del report. Sono disponibili le stesse proprietà, inclusa la possibilità di configurare il collegamento tra l'elemento dati e il relativo elemento padre. Vengono forniti gli stessi trigger ed è possibile inserire un elemento di dati o un intero grafo di elementi di dati nidificati contemporaneamente.
Questo esempio mostra due elementi di dati inseriti nell'ancoraggio. È previsto lo stesso supporto per le colonne degli elementi di dati normali. Business Central non supporta l'aggiunta di nuovi elementi di dati radice. È possibile inserire nuovi elementi di dati radice in uno degli elementi di dati esistenti. Se si prova a seguire questo approccio, viene visualizzato un errore del compilatore come mostrato nello screenshot seguente.
Estensione della pagina di richiesta
L'estensione della pagina di richiesta è supportata. Lo screenshot seguente mostra una pagina Richiesta di esempio.
Nella pagina di richiesta in un'estensione di report non è disponibile alcuna proprietà. La sezione del layout è simile a una pagina normale perché la pagina di richiesta è fondamentalmente una pagina, il che significa che l'estensione della pagina di richiesta è simile a un'estensione di pagina.
Le sezioni di layout sono analoghe alle estensioni di pagina:
- addafter()
- addbefore()
- addfirst()
- addlast()
- modify()
- moveafter()
- movebefore()
- movefirst()
- movelast()
Pertanto, è possibile spostarsi tra i campi e aggiungere campi alla pagina di richiesta di un'estensione di report. I campi che è possibile aggiungere alla pagina di richiesta sono simili a una normale pagina di richiesta di report.
È possibile aggiungere gli elementi seguenti in un'estensione del report o in membri protetti nel grafo delle dipendenze.
Colonne
Variabili
Espressioni
Procedure
I trigger sulla pagina di richiesta sono simili a quelli presenti in una pagina di richiesta di report e ciò significa che sono presenti sul nodo della pagina di richiesta. Saranno inoltre disponibili trigger per nuovi campi e campi modificati. Le sequenze di chiamata funzionano in modo simile a quelle delle pagine normali.
I trigger chiamati dopo verranno chiamati successivamente a quelli chiamati sull'oggetto base e gli altri trigger sostanzialmente eseguiranno una sostituzione o una sovrascrittura.
I trigger sul nodo requestpage sono:
- OnAfterGetCurrRecord
- OnAfterGetRecord
- OnClosePage
- OnDeleteRecord
- OnInsertRecord
- OnModifyRecord
- OnNewRecord
- OnOpenPage
- OnQueryClosePage
I trigger sui campi nuovo oggetto requestpage sono i seguenti:
- OnAfterLookup
- OnAssistEdit
- OnControlAddIn
- OnDrillDown
- OnLookup
- OnValidate
I trigger sui campi modifica oggetto requestpage sono i seguenti:
- OnAfterLookup
- OnAfterValidate
- OnAssistEdit
- OnBeforeValidate
- OnDrillDown
- OnLookup
Aggiunta di layout
Il processo di aggiunta di un layout come parte di un'estensione di report è simile a quello eseguito su un report normale. In un oggetto estensione di report è possibile aggiungere più layout. L'aggiunta di un layout a un'estensione di report non è obbligatoria. È importante sapere che l'estendibilità del layout non è supportata. È possibile sostituire solo un layout di report.
Quando si crea un'estensione di report in Visual Studio Code, spesso si desidera usare il layout del report di base come punto di partenza. Per usare questo approccio, occorre interagire con il cliente e scaricare il relativo layout di report, quindi aggiungerlo alla propria estensione di report.
I layer che fanno parte dell'estensione del report vengono distribuiti con l'applicazione padre e visualizzati come layout predefiniti. Questi nuovi layout non verranno assegnati automaticamente al report. È necessario selezionarli e impostarli manualmente nella pagina Layout di report oppure è possibile scrivere codice di installazione per automatizzare questa attività.
Altre estensioni di report potrebbero estendere lo stesso report, sovrascrivendo il codice di installazione. È possibile selezionare solo i tipi di layout supportati dal report di base.
Cosa accade in fase di disinstallazione
Quando si disinstalla un'estensione di report, il layout viene nascosto dall'interfaccia utente. In particolare, quando si disinstalla l'estensione di report, questa non sarà più disponibile nella posizione precedente per la selezione. I layout personalizzati rimarranno comunque disponibili. Se si dispone di un layout personalizzato che usa alcune colonne in un'estensione di report e si disinstalla quest'ultima, si riceve un errore di runtime durante l'esecuzione del report. Sarà necessario quindi correggerlo manualmente nel layout.