Oggetti contesto

  • 7 minuti

Quando si creano i gestori eventi e si usa l'API dello script client, è importante sapere quali sono gli oggetti contesto disponibili e come usarli. Lo scopo degli oggetti contesto è fornire informazioni sul contesto in cui viene eseguito il codice. Con questo contesto si può evitare di impostare come hardcoded le informazioni della logica. Il contesto permette di creare funzioni più generiche e di renderle meno sensibili alla struttura di layout specifica dei componenti dell'interfaccia utente in uso.

Contesto di esecuzione

Quando si registra un gestore eventi, è possibile passare il contesto di esecuzione come primo parametro. Se si registra un gestore eventi usando le proprietà del modulo, è possibile abilitare questa opzione. L'immagine mostra la registrazione di un gestore OnLoad e l'abilitazione del contesto di esecuzione.

Screenshot che mostra come abilitare il passaggio del contesto di esecuzione.

In genere, è consigliabile selezionare sempre questa opzione quando si registra un gestore eventi usando le proprietà del modulo. Quando si registra un gestore eventi usando il codice, questa opzione viene selezionata automaticamente.

La definizione della funzione che accetta il contesto di esecuzione come primo parametro avrà un aspetto simile al seguente:

Screenshot di una funzione che evidenzia il contesto di esecuzione come primo parametro.

L'uso più comune del contesto di esecuzione consiste nel recuperare i contesti del modulo e della griglia. Un altro metodo utile in questo contesto è getEventSource. L'origine dell'evento restituisce un riferimento all'oggetto che ha attivato l'evento. Questo oggetto permette di scrivere gestori generici che interrogano l'origine dell'evento in fase di esecuzione per individuare quale controllo ha attivato l'evento. Questo oggetto può risultare utile quando si vuole scrivere un singolo metodo che può essere registrato su eventi per più controlli, anziché creare un gestore eventi separato per ciascun controllo. Ad esempio, se è presente un evento OnChange per più campi, è possibile usare getEventSource per identificare il campo che ha attivato l'evento e usarlo di conseguenza.

Contesto modulo

Il contesto modulo dell'API client (formContext) fa riferimento al modulo o a un elemento del modulo, ad esempio un controllo visualizzazione rapida o una riga in una griglia modificabile, rispetto al quale viene eseguito il codice corrente. È possibile recuperare l'oggetto formContext dal contesto di esecuzione usando la funzione getFormContext.

Screenshot della funzione che usa il contesto di esecuzione per ottenere il contesto modulo.

In precedenza, l'accesso all'elemento o al modulo doveva essere eseguito mediante l'oggetto Xrm.Page globale. Tuttavia, nell'ultima versione, l'oggetto Xrm.Page è deprecato. Occorre invece usare il metodo getFormContext dall'oggetto contesto di esecuzione per ottenere un riferimento al modulo o all'elemento appropriato nel modulo. Quindi, anziché scrivere codice simile all'esempio seguente,

var firstName = Xrm.Page.getAttribute("firstname").getValue();

si dovrà scrivere il codice di seguito usando formContext.

var formContext = executionContext.getFormContext();

var firstName = formContext.getAttribute("firstname").getValue();

È possibile ottenere altre informazioni sulla deprecazione di Xrm.Page.

Il diagramma seguente mostra una panoramica generale delle proprietà e dei metodi disponibili nel contesto modulo:

Diagramma del modello a oggetti del contesto modulo.

Oggetto dati

L'oggetto dati (formContext.data) è destinato a essere usato per manipolare i dati di tabella all'interno del modulo.

Questa tabella è un riepilogo di ciascuno degli oggetti e delle raccolte che contengono l'oggetto dati:

Nome Descrizione
Attributi Raccolta di dati non di entità nel modulo. Gli elementi di questa raccolta appartengono allo stesso tipo di dati della raccolta di attributi nell'entità, ma è importante notare che non si tratta di attributi della tabella del modulo.
Entità Metodi per recuperare informazioni specifiche della riga visualizzata nella pagina, il metodo di salvataggio e una raccolta di tutti gli attributi inclusi nel modulo. I dati degli attributi sono limitati a quelli rappresentati dai campi nel modulo rispetto a tutti i campi disponibili nella configurazione dell'entità. Per altre informazioni, consultare formContext.data.entity.
Processo Oggetti e metodi per l'iterazione con i dati del flusso del processo aziendale in un modulo. Per altre informazioni, consultare formContext.data.process.

Oggetto interfaccia utente

L'oggetto interfaccia utente (formContext.ui) fornisce sia metodi per recuperare informazioni sull'interfaccia utente che raccolte per diversi componenti secondari del modulo o della griglia.

Questa tabella riepiloga ognuno degli oggetti e delle raccolte che contengono l'oggetto interfaccia utente:

Nome Descrizione
Controlli Raccolta di tutti i controlli della pagina. Per informazioni sulle raccolte, sui controlli e sugli oggetti controllo nella raccolta, consultare Raccolte.
FormSelector Metodi per ottenere informazioni sui moduli. Usare il metodo formSelector.getCurrentItem per recuperare le informazioni sul modulo attualmente in uso. Usare la raccolta formSelector.items per recuperare informazioni su tutti i moduli disponibili per l'utente.
Navigazione Raccolta di tutti gli elementi di spostamento nella pagina. Per informazioni sugli elementi della raccolta, consultare formContext.ui.navigation. L'oggetto spostamento non è disponibile per Microsoft Dynamics 365 per tablet. Per automatizzare lo spostamento nell'applicazione in generale, si usa in genere lo spazio dei nomi Xrm.Navigation.
Processo Oggetti e metodi per interagire con il controllo del flusso di processo aziendale in un modulo, ad esempio impostandone la visibilità. Per altre informazioni, consultare formContext.ui.process.
QuickForms Raccolta di tutti i controlli visualizzazione rapida in un modulo. Per altre informazioni, consultare formContext.ui.quickForms.
Schede Raccolta di tutte le schede della pagina. Per informazioni sugli elementi della raccolta, consultare formContex.ui.tabs.

In genere, quando è necessario ottenere o impostare un valore di colonna di tabella, si usa l'oggetto dati anziché l'oggetto interfaccia utente. L'oggetto dati ha un solo oggetto attributo che rappresenta il valore della colonna di tabella. L'oggetto interfaccia utente dispone invece di più controlli per la stessa colonna di tabella nel modulo, ognuno con un riferimento all'attributo. Pertanto, è più semplice usare l'oggetto dati per manipolare il valore dell'attributo e l'oggetto interfaccia utente per usare i controlli che rappresentano quell'attributo nel modulo.

L'uso degli oggetti contesto negli script li rende più resilienti alle modifiche nel modulo e nell'API client.