Birisi size bir Word şablonu ve bir teslim tarihi verir. Hangi veriye ihtiyaç duyuyor? Yaygın cevap, şablonu açmak, kaydırmak, tahmin etmek, çalıştırmak, hatayı okumak ve tekrar çalıştırmaktır. GroupDocs.Assembly.Mcp yerel olarak çalışırken (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor veya Copilot şablona doğrudan sorar: get_template_fields her etiketi, kullandığı veri adlarını ve doldurulacak bir JSON iskeletini, motoru çalıştırmadan döndürür ve bir çalıştırma başarısız olduğunda, hata neyi değiştirmeniz gerektiğini söyler:

order-lines.docx hangi verilere ihtiyaç duyuyor? Eğer oluşturulamıyorsa, nedenini ve şablonu nasıl düzelteceğimi söyle.

Yapılandırma ve sorun giderme ile adım adım sürüm belgelerde bulunabilir: Bir şablonun neye ihtiyacı olduğunu ve neden başarısız olduğunu nasıl öğrenilir.

Doldurmadan önce neden incelemelisiniz?

Çünkü deneme yanılma, bir şemayı öğrenmenin pahalı yoludur. Belgenin görünen metninden alan adlarını tahmin eden bir ajan, şablon customer.Name okurken CustomerName tahmin eder ve her yanlış tahmin bir tur gecikme ve kafa karıştırıcı bir hata maliyetine yol açar. Bir şablon bir nesir değildir; veri sözleşmesi olan bir programdır ve sözleşme okunabilir.

Bu, get_template_fields işlevinin yaptığı tek şeydir. <<…>> etiketlerini ayrıştırır, adları belirler ve iskeleti oluşturur:

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

Not, yöntemi dürüstçe açıklar: bu statik bir incelemedir. Select projeksiyonunda üretilen bir alan izlenmez. Normal bir sözleşme, mektup veya fatura şablonu için, iskelet doldurulması gereken tam şeydir.

İskelet aynı zamanda sizinle olan diyaloğu da değiştirir. “Siparişi oluşturmaya çalıştım ve başarısız oldu” demek yerine, ajan “bu şablon bir satır listesine ihtiyaç duyuyor, her biri bir başlık ve miktar içeriyor; e-postanızda üç tanesini buldum, işte burada” diyebilir ve ancak o zaman oluşturur. İnceleme ucuzdur, veri gerektirmez ve hiçbir şeye dokunmaz, bu yüzden ajan daha önce görmediği herhangi bir şablon için doğru ilk adımdır ve birisi şablonu düzenlediğinde tekrar doğru adımdır.

Üç hata, üç yanıt

şablon sorunu               sunucunun söylediği               çözüm
------------------------  ----------------------------  -------------------
{{name}} yer tutucuları     "2 '{{...}}' yer tutucu(lar).  write <<[name]>>
                          ... does not process that
                          syntax"
<<foreach>> hiç kapanmamış  "Unexpected end of template.  add <</foreach>>
                          A block tag is not closed"
veri bir alana sahip değil  "The template reads 'Email',  add it, or
                          which the data does not have" allowMissingMembers

Yanlış sözdizimi. Çok sayıda şablon, diğer motorlar için yazılmış ve {{name}} kullanır. GroupDocs.Assembly bunları metin olarak bırakır ve inceleme, kimsenin bir çalıştırmayı boşa harcamadan önce bunu söyler:

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

Kapanmamış blok. Bizim order-lines.docx bir <<foreach>> açar ve hiç kapatmaz. İnceleme etiketleri mutlu bir şekilde listeler; oluşturma ise yapmaz:

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

Eksik alan. Veri, şablonun okuduğu bir şeyi içermediğinde, hata alanı adını verir, adların büyük/küçük harfe duyarlı olduğunu söyler ve şu seçeneği sunar: allowMissingMembers: true eksik üyeler için hiçbir şey ve boş listeler üretir, hataya yol açmaz.

Şablon hatalarla dolu olduğunda

Bazı şablonlarda birden fazla hata bulunur ve bunları tek tek başarısız çalıştırmalarla düzeltmek yavaştır. inlineErrors: true şablonu kendi hata raporuna dönüştürür: belge oluşturulur ve her hatalı etiketin yanına mesajı yazılır. GroupDocs.Assembly örneklerinden bir örnek şablonda:

-> 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!'

Çıktı, belgedeki etiketin bulunduğu yerde << var [name] Error! An assignment operator is expected. >> içerir. Dosyayı açın, işaretlenmiş her etiketi düzeltin, bayrak olmadan tekrar çalıştırın.

İncelemenin göremediği şeyler

İkili Outlook şablonları bir istisnadır. Bir .msg dosyasının etiketleri, onu oluşturmadan okunamaz ve sunucu bunu, “alan yok” gibi görünen boş bir liste döndürmek yerine söyler:

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

Karşılaştığımız bir başka tuzak: veride boş bir liste, üye tiplerine sahip değildir. Sözleşme şablonumuz item.Quantity * item.UnitPrice çarpar; \"items\": [] ve allowMissingMembers: true ile, oluşturma yine “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”* hatasıyla başarısız olur. Ajanın, oluşturma yapmadan önce listenin boş olmadığını kontrol etmesini sağlayın ve boş bir sözleşmenin nasıl görünmesi gerektiğini sorun.

Dürüst sınırlamalar

  • İnceleme statiktir: Select ve GroupBy projeksiyonları izlenmez ve .msg şablonları okunamaz.
  • Şablonlar güvenilir girdidir; görüntü ve belge etiketleri ifadelerinin döndürdüğü yol ve URL’leri yükler.
  • Değerlendirme modu: her çıktı “Evaluation Only. Created with GroupDocs.Assembly 26.7…” ile başlar.
  • Tarihler: 2026-11-12T00:00:00 gönderin ve şablonda :"d MMMM yyyy" ile biçimlendirin; yalnızca tarih içeren bir dize UTC+2 makinede bir gün kaydırıldı ve "12.11.2026" 11 Aralık olarak okundu.

SSS

Bir Word şablonunun hangi alanlara ihtiyacı olduğunu nasıl görürüm?
Ajanı get_template_fields çağırması için isteyin. Etiketleri, veri adlarını ve bir JSON iskeletini yerel olarak, hiçbir şey oluşturmadan alırsınız.

Şablonum neden değeri yerine {{name}} yazdırıyor?
Çünkü GroupDocs.Assembly etiketleri <<[name]>> şeklindedir. Sunucunun incelemesi {{…}} yer tutucularını işaretler ve neyin yazılması gerektiğini söyler.

Markdown bir şablon olabilir mi?
Evet. product-readme.md dosyamızda <<[product]>> ve <<[description]>> etiketleri Word dosyası gibi incelendi ve doğrudan DOCX olarak üretildi.

Daha derine inin