Někdo vám předá Word šablonu a termín. Jaká data šablona potřebuje? Obvyklá odpověď je otevřít ji, projít, hádat, spustit, přečíst chybu a spustit znovu. S lokálně běžícím GroupDocs.Assembly.Mcp (dnx GroupDocs.Assembly.Mcp --yes) vám Claude Desktop, Cursor nebo Copilot položí šablonu přímo: get_template_fields vrátí každý tag, názvy dat, která používá, a JSON kostru k vyplnění, aniž by spouštěl engine, a když běh selže, chyba říká, co změnit:

Jaká data potřebuje order-lines.docx? Pokud se nevygeneruje, řekni mi proč a jak šablonu opravit.

Krok‑za‑krokem verze s konfigurací a řešením problémů je v dokumentaci: How to find out what a template needs and why it failed.

Proč kontrolovat před vyplněním?

Protože pokus‑a‑omyl je drahý způsob, jak se naučit schéma. Agent, který hádá názvy polí z viditelného textu dokumentu, uhodne CustomerName, když šablona čte customer.Name, a každé špatné uhodnutí stojí jeden tah a matoucí chybu. Šablona není prózou; je to program s datovou smlouvou, a smlouvu lze přečíst.

To je vše, co get_template_fields dělá. Rozebere tagy <<…>>, zjistí názvy a vytvoří kostru:

-> 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." ] }

Poznámka je upřímná ohledně metody: jedná se o statickou inspekci. Pole vytvořené uvnitř projekce Select není sledováno. Pro běžnou smlouvu, dopis nebo fakturu, je kostra přesně tím, co je potřeba vyplnit.

Kostra také mění konverzaci s vámi. Místo „Zkusil jsem vygenerovat objednávku a selhala“ může agent říct „tato šablona potřebuje seznam řádků, každý s názvem a množstvím; našel jsem tři ve vašem e‑mailu, tady jsou“, a až poté vygeneruje. Inspekce je levná, nepotřebuje žádná data a nedotýká se ničeho, takže je to správný první krok pro jakoukoli šablonu, kterou agent doposud neviděl, a opět správný krok vždy, když někdo šablonu upravil.

Tři selhání, tři odpovědi

problém šablony          co server říká                oprava
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 '{{...}}' placeholder(s).  napište <<[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

Špatná syntaxe. Mnoho šablon v praxi bylo napsáno pro jiné enginy a používá {{name}}. GroupDocs.Assembly je nechává jako text a inspekce to řekne dříve, než někdo zbytečně spustí:

-> 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." ] }

Neuzavřený blok. Naše order-lines.docx otevře <<foreach>> a nikdy jej neuzavře. Inspekce tagy vypíše spokojeně; generování ne:

-> 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>>.

Chybějící pole. Když data postrádají něco, co šablona čte, chyba pojmenuje pole, řekne, že názvy jsou citlivé na velikost písmen, a nabídne přepínač: allowMissingMembers: true nevrátí nic pro chybějící členy a místo selhání vrátí prázdné seznamy.

Když je šablona plná chyb

Některé šablony mají několik chyb a opravovat je po jednom selhání je pomalé. inlineErrors: true promění šablonu na vlastní zprávu o chybách: dokument se vygeneruje a každému chybnému tagu se zapíše zpráva vedle něj. Na ukázkové šabloně z příkladů 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!'

Výstup obsahuje << var [name] Error! An assignment operator is expected. >> na místě v dokumentu, kde tag stojí. Otevřete soubor, opravte každý označený tag a spusťte znovu bez příznaku.

Co inspekce nevidí

Binární Outlook šablony jsou výjimkou. Tagy v souboru .msg nelze přečíst bez jeho vygenerování a server to řekne místo toho, aby vrátil prázdný seznam, který vypadá jako „žádná pole“:

-> 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." ] }

Další past, na kterou jsme narazili: seznam, který je v datech prázdný, nemá typy členů. Naše smluvní šablona násobí item.Quantity * item.UnitPrice; s "items": [] a allowMissingMembers: true generování stále selže s “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. Nechte agenta zkontrolovat, že seznam není prázdný, než začne generovat, a zeptejte se, jak by měla vypadat prázdná smlouva.

Upřímná omezení

  • Inspekce je statická: projekce Select a GroupBy nejsou sledovány a šablony .msg nelze přečíst.
  • Šablony jsou důvěryhodný vstup; tagy pro obrázky a dokumenty načítají cesty a URL, které vrací jejich výrazy.
  • Režim hodnocení: každý výstup začíná “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
  • Data: předávejte 2026-11-12T00:00:00 a formátujte v šabloně pomocí :"d MMMM yyyy"; řetězec jen s datem byl posunut o den na stroji UTC+2 a "12.11.2026" byl přečten jako 11 prosince.

FAQ

Jak zjistím, jaká pole Word šablona potřebuje?
Požádejte agenta, aby na ni zavolal get_template_fields. Dostanete tagy, názvy dat a JSON kostru, lokálně, bez generování čehokoli.

Proč moje šablona vypisuje {{name}} místo hodnoty?
Protože tagy GroupDocs.Assembly jsou <<[name]>>. Inspekce serveru označí {{…}} zástupné znaky a řekne, co místo toho napsat.

Může být Markdown šablonou?
Ano. Náš product-readme.md s tagy <<[product]>> a <<[description]>> byl inspektován jako Word soubor a vygenerován přímo do DOCX.

Jděte hlouběji