کسی یک قالب Word و یک مهلت به شما می‌دهد. چه داده‌ای نیاز دارد؟ پاسخ معمول این است که آن را باز کنید، اسکرول کنید، حدس بزنید، اجرا کنید، خطا را بخوانید و دوباره اجرا کنید. با اجرای محلی GroupDocs.Assembly.Mcp (dnx GroupDocs.Assembly.Mcp --yes)، Claude Desktop، Cursor یا Copilot مستقیماً از قالب می‌پرسند: get_template_fields تمام تگ‌ها، نام‌های داده‌ای که استفاده می‌کند و یک اسکلت JSON برای پر کردن را برمی‌گرداند، بدون اینکه موتور را اجرا کند، و وقتی اجرا شکست می‌خورد، خطا می‌گوید چه چیزی را باید تغییر داد:

چه داده‌ای برای order-lines.docx لازم است؟ اگر تولید نمی‌شود، بگویید چرا و چگونه قالب را اصلاح کنید.

نسخه گام به گام با پیکربندی و عیب‌یابی در مستندات موجود است: چگونه بفهمیم یک قالب چه چیزی نیاز دارد و چرا شکست خورده است

چرا قبل از پر کردن بررسی کنیم؟

چون آزمون و خطا راه گران‌قیمتی برای یادگیری یک طرح‌واره است. یک عامل که نام فیلدها را از متن قابل مشاهده یک سند حدس می‌زند، CustomerName را وقتی قالب customer.Name نوشته شده است، حدس می‌زند و هر حدس اشتباه یک دور سفر و یک خطای گیج‌کننده هزینه دارد. یک قالب متن نیست؛ برنامه‌ای با قرارداد داده‌ای است و می‌توان این قرارداد را خواند.

این همان کاری است که get_template_fields انجام می‌دهد. تگ‌های <<…>> را تجزیه می‌کند، نام‌ها را استخراج می‌کند و اسکلت را می‌سازد:

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

یادداشت درباره روش صادقانه است: این یک بازرسی ایستایی است. فیلدی که داخل یک پروژکشن Select تولید می‌شود دنبال نمی‌شود. برای یک قرارداد عادی، قالب نامه یا فاکتور، اسکلت دقیقاً همان چیزی است که باید پر شود.

اسکلت همچنین گفت‌وگو با شما را تغییر می‌دهد. به جای «سعی کردم سفارش را تولید کنم و شکست خورد»، عامل می‌تواند بگوید «این قالب به یک لیست از خطوط نیاز دارد که هر کدام دارای عنوان و مقدار هستند؛ من سه مورد در ایمیل شما پیدا کردم، این‌ها هستند»، و فقط پس از آن تولید می‌کند. بازرسی ارزان است، نیازی به داده ندارد و هیچ چیزی را دست نمی‌زند، بنابراین اولین تماس مناسب برای هر قالبی است که عامل قبلاً آن را ندیده و دوباره تماس مناسب هر زمان که کسی قالب را ویرایش کرده باشد.

سه شکست، سه پاسخ

مشکل قالب                پیام سرور                                 راه‌حل
------------------------  ----------------------------               -------------------
{{name}} placeholders     "۲ '{{...}}' متغیر(ها).  write <<[name]>> 
                          ... does not process that syntax"       
<<foreach>> never closed  "Unexpected end of template.  add <</foreach>> 
                          A block tag is not closed"              
داده فاقد فیلد           "The template reads 'Email',  add it, or 
                          which the data does not have" allowMissingMembers

نحو اشتباه. بسیاری از قالب‌های موجود در طبیعت برای موتورهای دیگر نوشته شده‌اند و از {{name}} استفاده می‌کنند. GroupDocs.Assembly این‌ها را به عنوان متن می‌گذارد و بازرسی قبل از اینکه کسی یک اجرا را هدر بدهد، این را اعلام می‌کند:

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

بلاک بسته نشده. قالب order-lines.docx ما یک <<foreach>> باز می‌کند و هرگز آن را نمی‌بندد. بازرسی تگ‌ها را خوشحالانه فهرست می‌کند؛ اما تولید نمی‌کند:

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

فیلد گمشده. وقتی داده‌ای چیزی را که قالب می‌خواند نداشته باشد، خطا نام فیلد را می‌گوید، می‌گوید نام‌ها حساس به حروف بزرگ/کوچک هستند و سوئیچ allowMissingMembers: true را پیشنهاد می‌دهد که برای اعضای گمشده هیچ خروجی‌ای تولید نمی‌کند و لیست‌های خالی را به جای شکست برمی‌گرداند. این نکته فراتر از موتور است، همان‌طور که بخش بعدی نشان می‌دهد: یک لیست خالی هنوز وقتی قالب روی اعضای آن عملیات ریاضی انجام می‌دهد، شکست می‌خورد.

وقتی قالب پر از خطا باشد

برخی قالب‌ها چندین خطا دارند و رفع آن‌ها یک‌به‌یک با اجرای ناموفق زمان‌بر است. inlineErrors: true قالب را به گزارش خطای خودش تبدیل می‌کند: سند تولید می‌شود و هر تگ معیوب پیام خود را در کنار آن می‌نویسد. در قالب نمونه از مثال‌های 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!'

خروجی شامل << var [name] Error! An assignment operator is expected. >> در مکانی از سند که تگ قرار دارد، می‌شود. فایل را باز کنید، هر تگ علامت‌دار را اصلاح کنید و بدون پرچم دوباره اجرا کنید.

آنچه بازرسی نمی‌تواند ببیند

قالب‌های باینری Outlook استثنا هستند. تگ‌های یک فایل .msg بدون تولید آن قابل خواندن نیستند و سرور به جای برگرداندن لیست خالی که شبیه «بدون فیلد» به نظر می‌رسد، این را اعلام می‌کند:

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

یک تله دیگر که با آن مواجه شدیم: لیستی که در داده خالی است هیچ نوع عضوی ندارد. قالب قرارداد ما item.Quantity * item.UnitPrice را ضرب می‌کند؛ با "items": [] و allowMissingMembers: true، تولید هنوز با خطای “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”* شکست می‌خورد. محافظ واضح، <<if [items.Any()]>> دور جدول، کمکی نکرد: موتور قبل از اجرا تمام عبارات را بررسی می‌کند. کاری که کردیم این بود که محاسبه را از ردیف خارج کنیم. با مقدار که از قبل در داده وجود دارد (<<[item.Amount]>>) همان لیست خالی و allowMissingMembers: true سند را تولید کرد، و <<if [items.Count() == 0]>>No services ordered.<</if>> خط خود را چاپ کرد. در غیر این صورت، از عامل بخواهید قبل از تولید بررسی کند که لیست خالی نیست و از شما بپرسد یک قرارداد خالی باید چگونه به نظر برسد.

محدودیت‌های صادقانه

  • بازرسی ایستایی است: پروژکشن‌های Select و GroupBy دنبال نمی‌شوند و قالب‌های .msg قابل خواندن نیستند.
  • قالب‌ها ورودی مورد اعتماد هستند؛ تگ‌های تصویر و سند مسیرها و URLهایی را که عباراتشان برمی‌گرداند، بارگذاری می‌کنند.
  • حالت ارزیابی: هر خروجی با “Evaluation Only. Created with GroupDocs.Assembly 26.7…” شروع می‌شود.
  • تاریخ‌ها: 2026-11-12T00:00:00 را پاس دهید و در قالب با :"d MMMM yyyy" قالب‌بندی کنید؛ یک رشته فقط‑تاریخی در ماشین UTC+2 یک روز جابجا شد و "12.11.2026" به 11 دسامبر تفسیر شد.

سؤالات متداول

چگونه می‌توانم ببینم یک قالب Word چه فیلدهایی نیاز دارد؟
از عامل بخواهید get_template_fields را روی آن فراخوانی کند. تگ‌ها، نام‌های داده و یک اسکلت JSON را به‌صورت محلی و بدون تولید چیزی دریافت می‌کنید.

چرا قالب من {{name}} را چاپ می‌کند به‌جای مقدار؟
چون تگ‌های GroupDocs.Assembly به شکل <<[name]>> هستند. بازرسی سرور {{…}} را به‌عنوان متغیرهای جایگزین علامت‌گذاری می‌کند و می‌گوید به‌جای آن چه بنویسید.

آیا می‌توان Markdown را قالب کرد؟
بله. فایل product-readme.md ما با تگ‌های <<[product]>> و <<[description]>> همانند یک فایل Word بازرسی شد و مستقیم به DOCX تولید شد.

عمیق‌تر بروید