Qualcuno ti consegna un modello Word e una scadenza. Quali dati vuole? La risposta abituale è aprirlo, scorrere, indovinare, eseguirlo, leggere l’errore e rieseguirlo. Con GroupDocs.Assembly.Mcp in esecuzione locale (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor o Copilot interrogano direttamente il modello: get_template_fields restituisce ogni tag, i nomi dei dati che utilizza e uno scheletro JSON da compilare, senza eseguire il motore, e quando un’esecuzione fallisce, l’errore indica cosa modificare:

Quali dati richiede order-lines.docx? Se non verrà generato, dimmi perché e come correggere il modello.

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come scoprire di cosa ha bisogno un modello e perché è fallito.

Perché ispezionare prima di riempire?

Perché il tentativo‑errore è il modo costoso per apprendere uno schema. Un agente che indovina i nomi dei campi dal testo visibile di un documento indovinerà CustomerName quando il modello contiene customer.Name, e ogni errore di indovinamento comporta un round‑trip e un errore confuso. Un modello non è prosa; è un programma con un contratto di dati, e il contratto può essere letto.

Questo è tutto ciò che fa get_template_fields. Analizza i tag <<…>>, ricava i nomi e costruisce lo scheletro:

-> get_template_fields {"template":{"filePath":"order-lines.docx"}}
<- { "tagCount": 3,
     "dataSourceNames": [ "lines" ],
     "fields": [ "lines[].Title", "lines[].Quantity" ],
     "dataSkeleton": { "lines": [ { "Title": "", "Quantity": "" } ] },
     "notes": [ "fields and dataSkeleton are inferred from the tags,
       not from the engine; values computed by Select/GroupBy
       projections are not followed." ] }

La nota è onesta sul metodo: questa è un’ispezione statica. Un campo prodotto all’interno di una proiezione Select non viene seguito. Per un normale contratto, lettera o modello di fattura, lo scheletro è esattamente ciò che bisogna compilare.

Lo scheletro cambia anche la conversazione con te. Invece di “Ho provato a generare l’ordine e ha fallito”, l’agente può dire “questo modello richiede un elenco di righe, ciascuna con un titolo e una quantità; ne ho trovate tre nella tua email, eccole”, e solo allora generare. L’ispezione è economica, non richiede dati e non tocca nulla, quindi è la prima chiamata corretta per qualsiasi modello che l’agente non abbia ancora visto, e la chiamata corretta di nuovo ogni volta che qualcuno ha modificato il modello da allora.

Tre errori, tre soluzioni

template problem          what the server says          the fix
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 '{{...}}' placeholder(s).  write <<[name]>>
                          ... does not process that
                          syntax"
<<foreach>> never closed  "Unexpected end of template.  add <</foreach>>
                          A block tag is not closed"
data lacks a field        "The template reads 'Email',  add it, or
                          which the data does not have" allowMissingMembers

La sintassi errata. Molti modelli in circolazione sono stati scritti per altri motori e usano {{name}}. GroupDocs.Assembly li lascia come testo, e l’ispezione lo segnala prima che qualcuno sprechi un’esecuzione:

-> get_template_fields {"template":{"filePath":"shipping-notice.docx"}}
<- { "tagCount": 0, "notes": [ "No <<…>> tags were found: ...",
     "The template contains 2 '{{…}}' placeholder(s). GroupDocs.Assembly
      does not process that syntax and leaves it as text; write
      <<[name]>> instead." ] }

Il blocco non chiuso. Il nostro order-lines.docx apre un <<foreach>> e non lo chiude mai. L’ispezione elenca i tag felicemente; la generazione no:

-> assemble_document {"template":{"filePath":"order-lines.docx"},
     "dataJson":"{\"lines\":[{\"Title\":\"Cable\",\"Quantity\":2}]}"}
<- Document assembly failed for 'order-lines.docx': ...
   Unexpected end of template. A block tag is not closed: every
   <<foreach>> needs <</foreach>> and every <<if>> needs <</if>>.

Il campo mancante. Quando i dati non contengono qualcosa che il modello legge, l’errore indica il campo, afferma che i nomi sono sensibili al maiuscolo/minuscolo e offre l’opzione: allowMissingMembers: true non produce output per i membri mancanti e restituisce liste vuote invece di fallire. Questo suggerimento è più ampio del motore, come mostra la sezione successiva: una lista vuota fallisce comunque quando il modello esegue operazioni aritmetiche sui suoi membri.

Quando il modello è pieno di errori

Alcuni modelli hanno diversi errori, e correggerli uno per volta con esecuzioni fallite è lento. inlineErrors: true trasforma il modello nel proprio report di errore: il documento viene generato e ogni tag difettoso riceve il proprio messaggio scritto accanto. Sul modello di esempio proveniente dagli esempi di GroupDocs.Assembly:

-> assemble_document {"template":{"filePath":"inline-error.docx"},
     "dataJson":"{\"name\":\"x\"}","inlineErrors":true}
<- Assembled 'inline-error.docx' ... The template has errors: each one
   is written into the output next to its tag, starting with 'Error!'

L’output contiene << var [name] Error! An assignment operator is expected. >>, nel punto del documento in cui si trova il tag. Apri il file, correggi ogni tag contrassegnato, riesegui senza il flag.

Cosa l’ispezione non può vedere

I modelli binari di Outlook sono l’eccezione. I tag di un file .msg non possono essere letti senza generarlo, e il server lo segnala invece di restituire una lista vuota che sembra “nessun campo”:

-> get_template_fields {"template":{"filePath":"contracts-table.msg"}}
<- { "readable": false, "notes": [ "Tags cannot be read from a .msg
     template without generating it. Save the template as DOCX, XLSX,
     PPTX or EML to inspect it, or generate it with assemble_document
     and inlineErrors=true to see which fields fail." ] }

Un’altra trappola che abbiamo incontrato: una lista vuota nei dati non ha tipi di membri. Il nostro modello di contratto moltiplica item.Quantity * item.UnitPrice; con "items": [] e allowMissingMembers: true, la generazione falliva comunque con “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. La guardia ovvia, <<if [items.Any()]>> intorno alla tabella, non ha aiutato: il motore controlla ogni espressione prima di eseguirne una. Ciò che ha funzionato è stato tenere l’aritmetica fuori dalla riga. Con l’importo già nei dati (<<[item.Amount]>>), la stessa lista vuota e allowMissingMembers: true hanno prodotto il documento, e <<if [items.Count() == 0]>>No services ordered.<</if>> ha stampato la sua riga. Altrimenti, fai in modo che l’agente verifichi che una lista non sia vuota prima di generare, e chiedi a te come dovrebbe apparire un contratto vuoto.

Limiti onesti

  • L’ispezione è statica: le proiezioni Select e GroupBy non sono seguite, e i modelli .msg non possono essere letti.
  • I modelli sono input fidato; i tag immagine e documento caricano i percorsi e gli URL restituiti dalle loro espressioni.
  • Modalità di valutazione: ogni output inizia con “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
  • Date: passa 2026-11-12T00:00:00 e formatta nel modello con :"d MMMM yyyy"; una stringa solo data è stata spostata di un giorno su una macchina UTC+2, e "12.11.2026" è stata interpretata come 11 dicembre.

FAQ

Come faccio a vedere quali campi richiede un modello Word?
Chiedi all’agente di chiamare get_template_fields su di esso. Ottieni i tag, i nomi dei dati e uno scheletro JSON, localmente, senza generare nulla.

Perché il mio modello stampa {{name}} invece del valore?
Perché i tag di GroupDocs.Assembly sono <<[name]>>. L’ispezione del server segnala i segnaposto {{…}} e indica cosa scrivere al loro posto.

Il Markdown può essere un modello?
Sì. Il nostro product-readme.md con i tag <<[product]>> e <<[description]>> è stato ispezionato come un file Word e generato direttamente in DOCX.

Approfondisci