Alguém lhe entrega um modelo Word e um prazo. Que dados ele precisa? A resposta usual é abrir, rolar, adivinhar, executar, ler o erro e executar novamente. Com o GroupDocs.Assembly.Mcp rodando localmente (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor ou Copilot perguntam diretamente ao modelo: get_template_fields devolve todas as tags, os nomes de dados que ele usa e um esqueleto JSON para preencher, sem executar o motor, e quando uma execução falha, o erro indica o que mudar:

Que dados o order-lines.docx precisa? Se não gerar, diga‑me por quê e como corrigir o modelo.

A versão passo a passo com configuração e solução de problemas está na documentação: How to find out what a template needs and why it failed.

Por que inspecionar antes de preencher?

Porque tentativa e erro é a forma cara de aprender um esquema. Um agente que adivinha nomes de campos a partir do texto visível de um documento adivinará CustomerName quando o modelo lê customer.Name, e cada adivinhação errada custa uma ida‑e‑volta e um erro confuso. Um modelo não é prosa; é um programa com um contrato de dados, e o contrato pode ser lido.

É tudo que o get_template_fields faz. Ele analisa as tags <<…>>, descobre os nomes e constrói o esqueleto:

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

A nota é honesta sobre o método: esta é uma inspeção estática. Um campo produzido dentro de uma projeção Select não é seguido. Para um contrato, carta ou modelo de fatura normal, o esqueleto é exatamente o que deve ser preenchido.

O esqueleto também muda a conversa com você. Em vez de “tentei gerar o pedido e falhou”, o agente pode dizer “este modelo precisa de uma lista de linhas, cada uma com título e quantidade; encontrei três no seu e‑mail, aqui estão”, e só então gerar. Inspeção é barata, não precisa de dados e não altera nada, portanto é a primeira chamada correta para qualquer modelo que o agente ainda não tenha visto, e a chamada correta novamente sempre que alguém editou o modelo desde então.

Três falhas, três respostas

problema do modelo          o que o servidor diz          a correção
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 '{{...}}' placeholder(s).  escreva <<[name]>>"
                          "... não processa essa
                          sintaxe"
<<foreach>> never closed  "Fim inesperado do modelo.  adicione <</foreach>>"
                          "Uma tag de bloco não está fechada"
data lacks a field        "O modelo lê 'Email',  adicione‑o, ou
                          o dado não o possui" allowMissingMembers

A sintaxe errada. Muitos modelos na prática foram escritos para outros motores e usam {{name}}. O GroupDocs.Assembly deixa esses como texto, e a inspeção avisa isso antes que alguém desperdice uma execução:

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

O bloco não fechado. Nosso order-lines.docx abre um <<foreach>> e nunca o fecha. A inspeção lista as tags felizmente; a geração não:

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

O campo ausente. Quando os dados não contêm algo que o modelo lê, o erro nomeia o campo, informa que os nomes diferenciam maiúsculas de minúsculas e oferece a opção: allowMissingMembers: true não produz saída para membros ausentes e gera listas vazias em vez de falhar.

Quando o modelo está cheio de erros

Alguns modelos têm vários erros, e corrigi‑los um por vez, com execuções falhas, é lento. inlineErrors: true transforma o modelo em seu próprio relatório de erros: o documento é gerado e cada tag defeituosa recebe sua mensagem escrita ao lado. No modelo de exemplo dos exemplos do 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!'

A saída contém << var [name] Error! An assignment operator is expected. >>, no local do documento onde a tag está. Abra o arquivo, corrija cada tag marcada e execute novamente sem a flag.

O que a inspeção não pode ver

Modelos binários do Outlook são a exceção. As tags de um arquivo .msg não podem ser lidas sem gerá‑lo, e o servidor informa isso em vez de devolver uma lista vazia que pareça “sem campos”:

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

Mais uma armadilha que encontramos: uma lista vazia nos dados não tem tipos de membro. Nosso modelo de contrato multiplica item.Quantity * item.UnitPrice; com "items": [] e allowMissingMembers: true, a geração ainda falhou com “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. Faça o agente verificar se a lista não está vazia antes de gerar e pergunte‑lhe como deve ser um contrato vazio.

Limites honestos

  • A inspeção é estática: projeções Select e GroupBy não são seguidas, e modelos .msg não podem ser lidos.
  • Modelos são entrada confiável; tags de imagem e documento carregam os caminhos e URLs que suas expressões retornam.
  • Modo de avaliação: toda saída começa com “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
  • Datas: passe 2026-11-12T00:00:00 e formate no modelo com :"d MMMM yyyy"; uma string apenas de data foi deslocada em um dia numa máquina UTC+2, e "12.11.2026" foi interpretada como 11 de dezembro.

FAQ

Como vejo quais campos um modelo Word precisa?
Peça ao agente para chamar get_template_fields nele. Você obtém as tags, os nomes de dados e um esqueleto JSON, localmente, sem gerar nada.

Por que meu modelo imprime {{name}} em vez do valor?
Porque as tags do GroupDocs.Assembly são <<[name]>>. A inspeção do servidor sinaliza placeholders {{…}} e indica o que escrever em vez disso.

Markdown pode ser um modelo?
Sim. Nosso product-readme.md com tags <<[product]>> e <<[description]>> foi inspecionado como um arquivo Word e gerado diretamente para DOCX.

Aprofunde