มีคนส่งเทมเพลต Word ให้คุณพร้อมกับกำหนดเวลา ข้อมูลอะไรที่มันต้องการ? คำตอบทั่วไปคือเปิดมัน, เลื่อนดู, คาดเดา, รันมัน, อ่านข้อผิดพลาด, แล้วรันอีกครั้ง เมื่อรัน GroupDocs.Assembly.Mcp บนเครื่องโลคัล (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor หรือ Copilot จะสอบถามเทมเพลตโดยตรง: get_template_fields จะคืนค่าแท็กทั้งหมด, ชื่อข้อมูลที่ใช้และโครงกระดูก JSON เพื่อเติม, โดยไม่ต้องรันเอนจิน, และเมื่อการรันล้มเหลว, ข้อผิดพลาดจะบอกว่าต้องเปลี่ยนอะไร:

ข้อมูลอะไรที่ order-lines.docx ต้องการ? หากไม่สามารถสร้างได้, บอกเหตุผลและวิธีแก้ไขเทมเพลต

เวอร์ชันขั้นตอนต่อขั้นตอนพร้อมการตั้งค่าและการแก้ปัญหาอยู่ในเอกสาร: How to find out what a template needs and why it failed.

ทำไมต้องตรวจสอบก่อนเติมข้อมูล?

เพราะการลองและผิดพลาดเป็นวิธีที่มีค่าใช้จ่ายสูงในการเรียนรู้สคีม่า ตัวแทนที่คาดเดาชื่อฟิลด์จากข้อความที่มองเห็นในเอกสารจะคาดเดา 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 จะไม่ถูกตามติด. สำหรับสัญญาปกติ, จดหมายหรือเทมเพลตใบแจ้งหนี้, โครงกระดูกคือสิ่งที่ต้องเติมอย่างแม่นยำ.

โครงกระดูกยังเปลี่ยนการสนทนากับคุณด้วย แทนที่จะพูดว่า “ฉันพยายามสร้างออเดอร์แล้วล้มเหลว”, ตัวแทนสามารถบอกว่า “เทมเพลตนี้ต้องการรายการของบรรทัด, แต่ละบรรทัดมีหัวเรื่องและจำนวน; ฉันพบสามรายการในอีเมลของคุณ, นี่คือมัน” และจากนั้นจึงสร้าง การตรวจสอบนั้นมีค่าใช้จ่ายต่ำ, ไม่ต้องการข้อมูลและไม่กระทบอะไร, ดังนั้นจึงเป็นการเรียกแรกที่เหมาะสมสำหรับเทมเพลตใด ๆ ที่ตัวแทนยังไม่เคยเห็น, และการเรียกอีกครั้งที่เหมาะสมเมื่อมีคนแก้ไขเทมเพลตตั้งแต่ครั้งก่อน

ความล้มเหลือสามแบบ, คำตอบสามแบบ

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

ไวยากรณ์ที่ผิด. เทมเพลตจำนวนมากที่ใช้ในโลกจริงถูกเขียนสำหรับเอนจินอื่นและใช้ {{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’”*. ให้ตัวแทนตรวจสอบว่ารายการไม่ว่างก่อนสร้าง, และถามคุณว่าสัญญาที่ว่างควรเป็นอย่างไร.

ข้อจำกัดที่ตรงไปตรงมา

  • การตรวจสอบเป็นแบบสถิติ: การโปรเจกชัน 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.

ไปลึกกว่า