ปลั๊กอิน Signer
ลงนามเอกสาร PDF และ Word ด้วยลายเซ็นที่มองเห็นได้และตราปิดผนึกดิจิทัล
ปลั๊กอิน Signer จะวางลายเซ็นที่มองเห็นได้บนเอกสารและโดยค่าเริ่มต้นจะปิดผนึกด้วยลายเซ็นดิจิทัลที่โปรแกรมอ่าน PDF สามารถตรวจสอบได้ มันลงนามไฟล์ PDF และ Word (.docx) ลายเซ็นที่มองเห็นได้จะเป็นภาพ PNG เสมอ: วาด, พิมพ์, หรืออัปโหลดโดยผู้ลงนาม
| พื้นผิว | ใช้เมื่อ |
|---|---|
DocumentSigner (C#) | คุณลงนามบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
Drop-in widget (doconutSigner.js) | คุณต้องการหน้าจออัปโหลด, ลงนาม และดาวน์โหลดที่พร้อมใช้งานในหน้าเว็บของคุณ |
HTTP endpoints (?sign=open|run|download) | คุณสร้าง UI การลงนามของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย |
ลายเซ็นแต่ละอันจะถูกวางเพียงครั้งเดียวบนหน้าเดียว ชื่อผู้ลงนาม, เหตุผลและตำแหน่งสามารถเดินทางไปพร้อมกับมัน
ติดตั้งแพคเกจ
ติดตั้งปลั๊กอิน Signer รุ่นเสถียรล่าสุด:
dotnet add package Doconut.NET8.Signerเพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับรุ่นที่เอกสารนี้อธิบาย, ส่งเวอร์ชันแยกต่างหาก:
dotnet add package Doconut.NET8.Signer --version 26.10.0รักษาแพคเกจ Signer ให้เป็นเวอร์ชันเดียวกับ Doconut.NET8. ID ของแพคเกจคือ Doconut.NET8.Signer; .<version> จะปรากฏเฉพาะในชื่อไฟล์ที่ดาวน์โหลด .nupkg.
ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Signer.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; จะถูกอ่านพร้อมกับใบอนุญาตของตัวดู.
แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET8 ทำงาน: Windows, และ Linux ที่ใช้ glibc บนสถาปัตยกรรม x64 (ไม่รวม Alpine หรือดิสทริบิวชันที่ใช้ musl อื่นๆ) บน Linux ให้ติดตั้งไลบรารีการกำหนดค่าแบบอักษรก่อนที่เอกสารแรกจะเปิด:
apt-get update && apt-get install -y libfontconfig1บน RHEL, Fedora และดิสทริบิวชันที่คล้ายกัน แพคเกจคือ fontconfig. หากไม่มีมัน การเปิดเอกสารจะล้มเหลวพร้อมข้อความ The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
ลงทะเบียนปลั๊กอิน
เช่นเดียวกับปลั๊กอิน Doconut ทุกตัว, Signer จะลงทะเบียนกับ AddPlugin<TPlugin>() ภายใน AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});นั่นคือทั้งหมดที่ส่วนต่อประสาน C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddSignerWidget() (ดูที่ วิดเจ็ตแบบฝังตัว).
ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Signer หากไม่มี, AddDoconut() จะโยนข้อผิดพลาดขณะเริ่มต้น ก่อนที่แอปจะให้บริการคำขอ:
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.มันจะโยนข้อผิดพลาดเมื่อไม่มีใบอนุญาต, ไฟล์ TRIAL เก่า, ใบอนุญาตที่ไม่มี Signer, และใบอนุญาตแบบชำระเงินที่ใช้เกินช่วงเวอร์ชัน ใบอนุญาต Demo/NFR ชั่วคราวจะได้รับการยอมรับ ดูที่ การตั้งค่าใบอนุญาต เพื่อดูวิธีโหลดใบอนุญาต
การให้ใบอนุญาตและลายน้ำ
| สถานะใบอนุญาต | การเริ่มต้น | ลายเซ็นที่รับรอง | ลายเซ็นภาพ |
|---|---|---|---|
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, กำหนดค่าใบรับรองแล้ว | เริ่มทำงาน | ปิดผนึกด้วยใบรับรองของคุณ, สะอาด (watermarked: false) | สะอาด |
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, ไม่มีใบรับรอง | เริ่มทำงาน | ปฏิเสธ: No signing certificate configured. | สะอาด |
| ใบอนุญาตแบบชำระเงิน, ใบรับรองหมดอายุหรือยังไม่ถึงวันใช้งาน | เริ่มทำงาน (พร้อมวิดเจ็ตเปิดใช้งาน, มีการบันทึกคำเตือน) | ปฏิเสธ: The signing certificate expired on yyyy-MM-dd. | สะอาด |
| ใบอนุญาต Demo/NFR ชั่วคราว, ยังใช้งานหรือหมดอายุ | เริ่มทำงาน | ปิดผนึกด้วยใบรับรอง Demo ที่สร้างมาในตัว, มีลายน้ำ (watermarked: true) | มีลายน้ำ |
ไม่มีใบอนุญาต, ไฟล์ TRIAL เก่า, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชัน | AddDoconut() จะโยนข้อผิดพลาด | — | — |
กฎนี้เหมือนกันสำหรับส่วนต่อประสาน C# และวิดเจ็ต: ผลลัพธ์จะมีลายน้ำเมื่อใบอนุญาตไม่ใช่ใบอนุญาตผู้ดูแบบชำระเงินหรือเป็นใบอนุญาตชั่วคราว ภายใต้ใบอนุญาตชั่วคราวปลั๊กอินจะลงนามด้วยใบรับรอง Demo ที่สร้างมาในตัวเสมอ และใบรับรองใดๆ ที่คุณกำหนดจะไม่ได้ใช้
ใบรับรอง Demo สร้างตราปิดผนึกที่แท้จริง แต่โปรแกรมอ่าน PDF จะไม่เชื่อถือมัน การบูรณาการสามารถสร้างและทดสอบแบบครบวงจรบนใบอนุญาตประเมินผล; เพื่อให้ได้ผลลัพธ์ที่สะอาดและเชื่อถือได้ คุณต้องมีทั้งใบอนุญาตแบบชำระเงินและ ใบรับรองการลงนาม ของคุณเอง.
การใช้จาก C#
DocumentSigner ถูกลงทะเบียนโดย AddDoconut() และดึงมาจากการฉีดพึ่งพา. ตัวสร้างของมันเป็น internal, ดังนั้นอย่า new มัน. การดึงโดยไม่มี AddPlugin<SignerPlugin>() จะทำให้เกิด No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
using Doconut;
using Doconut.Core.Models.Signing;
public sealed class ContractSigning
{
private readonly DocumentSigner _signer;
public ContractSigning(DocumentSigner signer) => _signer = signer;
public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
{
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
SignerName: "Ada Lovelace",
Reason: "I approve this document",
Location: "London, UK");
// โหมดตั้งค่าเริ่มต้นเป็น Certified (visible signature + digital seal); WordOutput มีค่าเริ่มต้นเป็น Pdf.
SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
using (result.Stream)
using (var output = new MemoryStream())
{
await result.Stream.CopyToAsync(output, ct);
return output.ToArray();
}
}
}SignAsync รับสตรีมต้นทาง, ส่วนขยายของมัน (".pdf" หรือ ".docx"), คำขอ, และใบรับรอง สำหรับการเรียกนี้. ชั้นหน้า (facade) ไม่ได้อ่าน SignerWidgetOptions.SigningCertificate; การตั้งค่านั้นเป็นสำหรับวิดเจ็ต. ส่ง null ภายใต้ใบอนุญาตทดลอง, หรือในโหมด Visual.
SignResult เก็บเอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, พร้อมกับ Extension ของมัน (".pdf" หรือ ".docx") เพื่อให้คุณสามารถตั้งชื่อไฟล์ได้. คุณเป็นเจ้าของสตรีม: ปล่อย (dispose) มันเมื่อเสร็จสิ้น.
ลายเซ็น Visual จะทำการประทับภาพเท่านั้นและไม่ต้องการใบรับรอง:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");
var request = new SignRequest(
new VisibleSignature(SignatureKind.Image, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
Mode: SignatureMode.Visual);
SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);แหล่ง Word จะถูกลงนามเป็น PDF เว้นแต่คุณขอผลลัพธ์เป็น Word. ตั้งชื่อผลลัพธ์จาก result.Extension:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
WordOutput: WordOutput.Docx);
SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension; // ".docx"SignAsync จะทำการ throw แทนการคืนค่าเมื่อการเรียกไม่สำเร็จ:
| Exception | Message | When |
|---|---|---|
InvalidOperationException | No signing certificate configured. | โหมด Certified, ใบอนุญาตแบบชำระเงิน, และไม่มีการส่งใบรับรอง |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | โหมด Certified พร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผล |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | ไบต์ PNG ว่างเปล่า, หรือการวางตำแหน่งที่ไม่ถูกต้อง |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | ประเภทแหล่งอื่นใด |
โหมดการลงนาม, ผลลัพธ์ Word และใบรับรอง
โหมดการลงนาม
SignRequest.Mode เลือกว่าลายเซ็นจะถูกปิดผนึกหรือไม่.
| Mode | What it produces | Certificate | Verifiable |
|---|---|---|---|
SignatureMode.Certified (default) | ลายเซ็นที่มองเห็นได้พร้อมตราดิจิทัล | จำเป็นภายใต้ใบอนุญาตแบบชำระเงิน | Yes |
SignatureMode.Visual | ลายเซ็นที่มองเห็นได้เท่านั้น | ไม่จำเป็น | No: เป็นเพียงรูปภาพ |
ใช้ Certified เมื่อลายเซ็นต้องสามารถพิสูจน์ได้: การอนุมัติ, สัญญา, สิ่งใดที่ผู้ตรวจสอบต้องตรวจสอบเพื่อยืนยันตัวตนและความสมบูรณ์. ใช้ Visual เมื่อคุณต้องการเพียงรูปลักษณ์ของลายเซ็น, หรือไม่มีใบรับรอง. ใบอนุญาตชั่วคราวจะใส่น้ำลายน้ำทั้งสองแบบ.
ตรา PDF คือลายเซ็นแบบแยก (detached) PKCS#7 (adbe.pkcs7.detached) ด้วย SHA-256, สำหรับคีย์ RSA หรือ ECDSA. พวกมันบรรจุใบรับรองของผู้ออกที่พบในไฟล์ PFX ของคุณ, ดังนั้นผู้อ่านที่เชื่อถือรากของคุณสามารถสร้างสายการตรวจสอบได้. ตราที่เป็นของ Word เป็นลายเซ็นแพ็กเกจ OOXML และบรรจุเฉพาะใบรับรองของผู้ลงนามเท่านั้น.
เอกสาร Word
สำหรับแหล่งข้อมูล .docx, SignRequest.WordOutput จะเลือกผลลัพธ์. จะถูกละเว้นสำหรับแหล่งข้อมูล PDF ซึ่งจะสร้าง PDF เสมอ.
| ผลลัพธ์ | สิ่งที่เกิดขึ้น | การสนับสนุนตัวตรวจสอบ |
|---|---|---|
WordOutput.Pdf (ค่าเริ่มต้น) | เอกสารถูกแปลงเป็น PDF, จากนั้นทำการเซ็นและปิดผนึก | กว้าง: PDF ที่เซ็นแล้วตรวจสอบได้ทุกที่ |
WordOutput.Docx | เอกสารถูกเก็บเป็น Word: ภาพลายเซ็นจะถูกวางลงในเอกสาร, พร้อมลายเซ็นแพ็กเกจ OOXML | จำกัด: ไม่ใช่ทุกโปรแกรมแสดงลายเซ็นแพ็กเกจ OOXML |
เก็บเป็น PDF เว้นแต่ผู้รับต้องการไฟล์ Word ที่แก้ไขได้และยอมรับการสนับสนุนตัวตรวจสอบที่จำกัด
การตั้งค่าใบรับรอง
เพื่อปิดผนึกด้วยอัตลักษณ์ของคุณเอง, ให้ปลั๊กอินไฟล์ PFX (PKCS#12) ที่รวมคีย์ส่วนตัวไว้. สำหรับวิดเจ็ต, ตั้งค่า SignerWidgetOptions.SigningCertificate; สำหรับฟาซาเด C#, ส่งใบรับรองไปยัง SignAsync. ให้ทั้งไบต์หรือพาธ, พร้อมรหัสผ่าน:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});ใบรับรองจะถูกเก็บไว้ในหน่วยความจำเท่านั้น. จะไม่มีการบันทึก, ส่งกลับให้ไคลเอนต์, หรือบันทึกลงฐานข้อมูล, และรหัสผ่านจะไม่ปรากฏในบรรทัดบันทึกหรือข้อความแสดงข้อผิดพลาดใด ๆ
ข้อกำหนด:
- PFX / PKCS#12 ชุด พร้อมคีย์ส่วนตัว. ไฟล์ที่มีเฉพาะคีย์สาธารณะ (
.cer,.crt) ไม่สามารถเซ็นได้. ส่งออกสายการออกใบรับรองพร้อมกับมัน, เพื่อให้ซีล PDF สามารถบรรจุได้ - รหัสผ่านที่ถูกต้อง
- อยู่ใน ช่วงเวลาที่ใช้งานได้. ใบรับรองที่หมดอายุหรือยังไม่ถึงวันเริ่มใช้งานจะไม่ทำให้แอปหยุดทำงาน: จะบันทึกเป็น Warning ตอนเริ่มต้น, และลายเซ็น Certified จะถูกปฏิเสธจนกว่าจะเปลี่ยนใหม่. ลายเซ็น Visual จะไม่ได้รับผลกระทบ
- ออกสำหรับการเซ็นเอกสาร: การใช้คีย์ที่มี digital signature หรือ non-repudiation, และการใช้คีย์ขยาย (extended key usage) หากมี, ที่อนุญาตให้เซ็นเอกสาร, ปกป้องอีเมล หรือยืนยันตัวตนของไคลเอนต์. ใบรับรองที่ออกเพื่อวัตถุประสงค์อื่น, เช่น ใบรับรองเซิร์ฟเวอร์ TLS, ยังคงสามารถเซ็นได้, แต่จะบันทึกเป็น Warning และโปรแกรมอ่าน PDF จะทำเครื่องหมายว่าลายเซ็นนั้น
- โทเค็นฮาร์ดแวร์, สมาร์ทการ์ด, HSMs และที่เก็บใบรับรองของ Windows ไม่ได้รับการสนับสนุน. ส่งออกใบรับรองพร้อมคีย์ส่วนตัวและสายการออกเป็น PFX
สร้าง PFX จากใบรับรองและคีย์ส่วนตัว ด้วย OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# รหัสผ่านการส่งออกที่คุณถูกขอคือ SigningCertificate.Password.ส่งออกจากที่เก็บใบรับรองของ Windows: เปิด certmgr.msc และค้นหาใบรับรอง (ไอคอนจะแสดงกุญแจเมื่อมีคีย์ส่วนตัว). คลิกขวา, เลือก All Tasks → Export…, เลือก Yes, export the private key, เลือก Personal Information Exchange – PKCS #12 (.PFX), แล้วตั้งรหัสผ่าน
การตรวจสอบเมื่อเริ่มต้น
เมื่อวิดเจ็ตถูกเปิดใช้งาน, ใบรับรองใน SignerWidgetOptions.SigningCertificate จะถูกตรวจสอบครั้งเดียว, ภายใน AddDoconut(), ดังนั้น PFX ที่กำหนดค่าไม่ถูกต้องจะล้มเหลวตอนเริ่มต้นแทนที่จะเกิดขึ้นที่ลายเซ็นแรก. ปัญหา 3 ประการจะทำให้เกิด InvalidOperationException:
| ข้อความ | วิธีแก้ |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | แก้ไข PfxPath; ตรวจสอบให้ไฟล์ถูกปรับใช้และอ่านได้โดยบัญชีของแอป |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | ตรวจสอบรหัสผ่าน; ตรวจสอบให้ไฟล์เป็น .pfx จริง, ไม่ใช่ .cer หรือ .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | ส่งออก PFX อีกครั้งพร้อมคีย์ส่วนตัว |
หากไม่มีปัญหา, โฮสต์จะเขียนบรรทัดเดียวลงบันทึกเมื่อเริ่มทำงาน. ข้อมูลเมื่อใบรับรองพร้อมใช้งาน:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Warning เมื่อใบรับรองหมดอายุ, ยังไม่ถึงวันเริ่มใช้งาน, หรือไม่ได้ออกสำหรับการเซ็นเอกสาร:
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.และ Information เมื่อไม่มีการกำหนดค่าใบรับรอง:
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.บรรทัดสุดท้ายนี้เหมือนกันในทุกไลเซนส์. ใต้ไลเซนส์แบบชำระเงิน, ใบรับรองสาธิตจะไม่ถูกใช้: หากไม่มีใบรับรอง, จะทำงานได้เฉพาะลายเซ็น Visual เท่านั้น
ฟาซาเด C# จะไม่ถูกตรวจสอบตอนเริ่มต้น. ใบรับรองที่คุณส่งไปยัง SignAsync จะถูกอ่านเมื่อคุณเซ็น, ดังนั้นพาธหรือรหัสผ่านที่ผิดจะทำให้การเรียกนั้นล้มเหลว.
วิดเจ็ตแบบดรอปอิน
เปิดใช้งาน endpoints
วิดเจ็ตของ ?sign=open|run|download endpoints มีค่า ปิดโดยค่าเริ่มต้น. เปิดใช้งานพวกมันข้างการลงทะเบียนปลั๊กอิน:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // ค่าเริ่มต้น
widget.MaxSignatureImageKb = 512; // ค่าเริ่มต้น
// widget.SigningCertificate: ดูการตั้งค่า Certificate; ปล่อยให้เป็น null สำหรับการลงนามสาธิต (มีลายน้ำ)
});
});AddSignerWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น. มันไม่ได้ให้สิทธิ์การลงนามโดยตัวเอง: ต้องการ AddPlugin<SignerPlugin>(), หรือ AddDoconut() จะโยนข้อผิดพลาด:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.หากไม่มี AddSignerWidget(), ทุกคำขอ ?sign= จะตอบกลับด้วย 404. สคริปต์เองยังคงให้บริการ, ดังนั้นวิดเจ็ตจะโหลดและวาดโซนดรอปของมัน, จากนั้นรายงาน Signing is not enabled on this server. ในคำขอแรกของมัน.
ฝังมัน
UseDoconutResources() ให้บริการสคริปต์ที่ {ResourcesPath}/js/doconutSigner.js (ค่าเริ่มต้น /doconut-res/js/doconutSigner.js). มันเป็นไฟล์เดียวที่รวมทุกอย่างโดยไม่มีการพึ่งพา:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>Doconut.signer(selectorOrElement, options) รับ CSS selector หรือ element, จะโยนข้อผิดพลาดหากไม่พบ mount, และคืนค่า handle.
ผู้ลงนามอัปโหลดไฟล์ PDF หรือไฟล์ .docx, สร้างลายเซ็น (วาด บน canvas, พิมพ์ ชื่อในฟอนต์ลายเซ็น, หรือ รูปภาพ จาก PNG, JPG หรือ GIF), ลากและปรับขนาดบนหน้า, แล้วลงนามและดาวน์โหลดผลลัพธ์. วิดเจ็ตจะส่งลายเซ็นเป็น PNG เสมอ; ภาพที่อัปโหลดจะถูกแปลงในเบราว์เซอร์เป็น PNG ที่มีขนาด 520×160.
ตัวเลือก
| ตัวเลือก | ชนิด | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | '/doconut' | ที่ที่ endpoints ?sign= และภาพตัวอย่างถูกให้บริการ |
resPath | string | '/doconut-res' | สงวนไว้; วิดเจ็ตรวม CSS ของตัวเอง |
maxUploadMb | number | 25 | ตรวจสอบเฉพาะด้านไคลเอนต์, ดังนั้นไฟล์ที่ใหญ่เกินจะล้มเหลวอย่างรวดเร็ว. ขีดจำกัดของเซิร์ฟเวอร์คือ MaxUploadMb ใน AddSignerWidget |
maxSignatureKb | number | 512 | ขีดจำกัดด้านไคลเอนต์สำหรับโหมด Image. ให้เท่ากับ MaxSignatureImageKb ของเซิร์ฟเวอร์ |
previewWidth | number | 560 | ความกว้างพิกเซลของตัวอย่างหน้า |
licenseUrl | string | null | null | เปลี่ยนข้อความแจ้งเตือน demo-watermark ให้เป็นลิงก์ไปยัง URL นี้ |
signatureMode | string | 'certified' | ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าที่อื่นจะกลายเป็น 'certified' |
showSignatureModeToggle | boolean | true | แสดงตัวเลือก ลายเซ็นดิจิทัล / เฉพาะภาพ. หากมี false, วิดเจ็ตจะลงนามด้วย signatureMode |
wordOutput | string | 'pdf' | ผลลัพธ์เริ่มต้นสำหรับแหล่งที่มาของ .docx: 'pdf' หรือ 'docx'. ค่าที่อื่นจะกลายเป็น 'pdf' |
showOutputFormatToggle | boolean | true | แสดงตัวเลือก PDF / Word, เฉพาะแหล่งที่มาของ .docx. หากมี false, วิดเจ็ตจะใช้ wordOutput |
labels | object | {} | แทนที่ส่วนใดส่วนหนึ่งของสตริงภาษาอังกฤษ |
การซ่อน toggle ไม่ได้ปิดการทำงานของฟีเจอร์; มันกำหนดค่าคงที่. มีการกำหนดค่าที่พบบ่อยสองแบบ:
// แสดงสวิตช์ทั้งสอง, ลายเซ็นดิจิทัลเป็นค่าเริ่มต้น: ผู้ลงนามแบบเซลฟ์เซอร์วิสเต็มรูปแบบ.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// แสดงผลอย่างเดียว, ไม่มีสวิตช์: ตราประทับง่ายๆ ที่ไม่มีลายเซ็นดิจิทัล
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});คอลแบ็ก
| คอลแบ็ก | เกิดเมื่อ | เพย์โหลด |
|---|---|---|
onReady | ครั้งเดียว, ที่การ mount (ไม่อีกครั้งบน reset()) | — |
onSourceLoaded | ไฟล์ถูกเปิดและแสดงตัวอย่างของมัน | { file: { token, name, pages, ext } } |
onSigned | การลงนามสำเร็จ | { downloadToken, downloadName, watermarked } |
onDownload | เมื่อคลิก Download ทุกครั้ง | { downloadName, downloadToken } |
onError | ขั้นตอนเปิด, ลงนาม หรือดาวน์โหลดล้มเหลว, หรือไฟล์โหมด Image มีขนาดใหญ่เกินไป | { message } |
คอลแบ็กที่โยนข้อยกเว้นจะถูกจับและบันทึก; มันจะไม่ทำให้การทำงานของวิดเจ็ตหยุดชะงัก.
การจัดการเชิงบังคับ
| วิธีการ | พฤติกรรม |
|---|---|
reset() | กลับไปที่หน้าจอดรอปและล้างการไหลปัจจุบัน ไม่ทำการเรียก onReady อีกครั้ง ไม่ทำอะไรหลังจาก destroy() |
loadFile(file) | เริ่มการไหลด้วย File. ไม่ทำอะไรหากวิดเจ็ตไม่อยู่ที่หน้าจอดรอป; เรียก reset() ก่อนหากจำเป็น |
destroy() | ลบผู้ฟัง, ทำให้ mount ว่างเปล่า, และทำให้อินสแตนซ์ค้าง |
const signerWidget = Doconut.signer('#host', {
basePath: '/doconut',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());ป้ายกำกับ
ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels จะทับส่วนใดส่วนหนึ่งและส่วนที่เหลือจะคงเป็นภาษาอังกฤษ ชิ้นส่วนที่เปลี่ยนแปลงในเวลารันใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.
| คีย์ | ค่าเริ่มต้นภาษาอังกฤษ |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
คีย์เพิ่มเติมครอบคลุมขั้นตอนการวาง, หน้าจอข้อผิดพลาด, แบบฟอร์มที่เชื่อมโยงของประกาศสาธิต (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) และประกาศ aria-live.
เมื่อ open หรือ run ตอบ 404 โดยไม่มีข้อผิดพลาด JSON, วิดเจ็ตจะแสดง signingNotEnabled. ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะชนะเสมอ, ดังนั้นข้อความเช่นการอัปโหลดที่หมดอายุจะยังคงแสดงอยู่.
การตั้งธีม
วิดเจ็ตเพิ่มคลาส dsw ไปยังองค์ประกอบ mount ของมันและอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS แบบกำหนดเอง, ดังนั้นคุณสามารถตั้งธีมได้โดยไม่ต้องแก้ไขภายใน:
#host.dsw {
--dsw-accent: #b0522b; /* ลิงก์, โฟกัส, โหมดทำงาน */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* โหมด Type */
}ค่าเริ่มต้น: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, ฟอนต์ UI ของระบบ, และฟอนต์ลายเซ็นแบบลายมือ.
สร้างส่วนหน้าของคุณเอง
วิดเจ็ตเป็นไคลเอนต์สำหรับสัญญา HTTP นี้ ทั้งสามเส้นทางอยู่ภายใต้พาธที่ UseDoconut() ถูกเมานท์ (โดยปกติ /doconut), และพวกมันตอบกลับ 404 จนกว่า AddSignerWidget() จะถูกเรียก ข้อผิดพลาดจะมีเนื้อหา JSON, { "error": "..." }, ยกเว้นในกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?sign= จะตอบกลับ 400.
| เส้นทาง | วัตถุประสงค์ | การตอบสนองสำเร็จ |
|---|---|---|
POST ?sign=open (หลายส่วน, หนึ่งไฟล์) | อัปโหลด PDF หรือ .docx และเปิดเพื่อดูตัวอย่าง | 200 — { token, name, pages, ext } |
POST ?sign=run (เนื้อหา JSON) | เซ็นไฟล์ที่อัปโหลด | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | สตรีมไฟล์ที่เซ็นแล้ว | 200 — ไฟล์, Content-Disposition: attachment, Cache-Control: no-store |
ext ในการตอบสนอง open มีจุดนำหน้า (".docx"). การแสดงตัวอย่างหน้าใช้เส้นทางรูปภาพผู้ชมมาตรฐาน, {basePath}?token={token}&page={n}&thumb=1&width={px}; หน้าแสดงผลจะกลายเป็น placement.page.
ส่วนเนื้อหา run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| ฟิลด์ | หมายเหตุ |
|---|---|
token | โทเค็นจาก open |
signature.kind | Drawn, Typed หรือ Image, ไม่สนใจตัวพิมพ์ใหญ่/เล็ก; อย่างอื่นจะกลายเป็น Drawn. เพียงแค่บอก: payload จะเป็น PNG เสมอ |
signature.payload | PNG base64 แบบเปล่า, ไม่มีคำนำหน้า data:. ต้องเป็น PNG จริงและไม่ใหญ่กว่า MaxSignatureImageKb หลังจากถอดรหัส |
placement.page | เริ่มจาก 1 |
placement.x / y / w / h | Normalized 0..1 จากมุมบนซ้าย, พร้อมกับ x + w ≤ 1 และ y + h ≤ 1 |
meta.signerName / reason / location | เป็นตัวเลือก. แต่ละรายการจะถูกตัดขอบ, ค่าที่ว่างจะถูกละทิ้ง, และแต่ละรายการจะถูกตัดที่ 256 ตัวอักษร |
wordOutput | pdf (ค่าเริ่มต้น) หรือ docx; จะถูกละเลยสำหรับแหล่ง PDF. อย่างอื่นจะกลายเป็น pdf |
mode | certified (ค่าเริ่มต้น) หรือ visual. อย่างอื่นจะกลายเป็น certified |
downloadName ตามผลลัพธ์: <source>-signed.pdf หรือ <source>-signed.docx, และ download ส่ง Content-Type ที่ตรงกัน.
แหล่งที่อัปโหลดและผลลัพธ์ที่เซ็นจะถูกเก็บไว้แต่ละรายการเป็นเวลา 30 นาที. หลังจากนั้น, run และ download จะตอบกลับ 404 และไฟล์ต้องเปิดใหม่อีกครั้ง. โทเค็นทั้งหมดเป็น GUID.
| เส้นทาง | สถานะ | เมื่อ | เนื้อหา |
|---|---|---|---|
| any | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน | status only |
| any | 405 | คำกริยาไม่ถูกต้อง (open และ run ต้องการ POST, download ต้องการ GET) | status only |
open | 400 | ไม่ใช่การอัปโหลดแบบ multipart | Expected a multipart file upload. |
open | 400 | ไม่มีไฟล์ หรือไฟล์ว่าง | No file uploaded. |
open | 400 | อย่างอื่นที่ไม่ใช่ .pdf หรือ .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | การอัปโหลดเกิน MaxUploadMb | File is too large. |
run | 400 | เนื้อหาไม่เป็น JSON ที่ถูกต้อง, หรือว่างเปล่า | Malformed request. / Empty request. |
run | 400 | โทเค็นหายหรือไม่ใช่ GUID | Invalid token. |
run | 404 | การอัปโหลดหมดอายุหรือไม่เคยเปิด | Upload expired — please re-open the file. |
run | 400 | ไม่มีลายเซ็น, หรือไม่มีการวาง | No signature supplied. / No placement supplied. |
run | 400 | payload ไม่ใช่ base64, ว่างเปล่า, ใหญ่เกินไป, หรือไม่ใช่ PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | การวางอยู่นอกหน้า | The signature or its placement is invalid. |
run | 400 | โหมดรับรอง, ใบอนุญาตชำระเงินและไม่มีใบรับรอง | No signing certificate configured. |
run | 400 | โหมดรับรองพร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผล | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | การประมวลผลล้มเหลว | A sanitized message |
download | 400 | โทเค็นหายหรือไม่ใช่ GUID | status only |
download | 404 | โทเค็นไม่รู้จักหรือหมดอายุ | status only |
การเดินทางรอบสมบูรณ์ด้วย fetch:
// file: ไฟล์ที่ต้องเซ็น; pngBase64: ลายเซ็นในรูปแบบ base64 PNG, โดยไม่มีคำนำหน้า data:,
// เช่น canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: อัปโหลดไฟล์
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: เซ็น
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: ดึงไฟล์ที่เซ็นแล้ว
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}จุดเชื่อมต่อเป็น same-origin: เวอร์ชันนี้ไม่มีการสนับสนุน CORS. ให้บริการ UI ของคุณและสคริปต์วิดเจ็ตจากต้นทางเดียวกับ Doconut, หรือทำ reverse-proxy ทั้งสองเส้นทาง /doconut (เส้นทาง middleware และเส้นทาง resources) ภายใต้ต้นทางของ UI ของคุณ.
ในการผลิต
-
ติดตั้งปลั๊กอิน ข้างๆ แพ็กเกจหลัก, ที่เวอร์ชันเดียวกัน:
dotnet add package Doconut.NET8.Signer. -
เพิ่มไฟล์ใบอนุญาต วาง
Doconut.Viewer.Signer.licในโฟลเดอร์เดียวกับDoconut.Viewer.lic. -
รับใบรับรองของคุณเป็น PFX พร้อมกับคีย์ส่วนตัวและสายการออกใบรับรอง, จากหน่วยงานออกใบรับรองหรือ PKI ขององค์กรของคุณ. เพื่อทดลองก่อน, ใช้ใบอนุญาตเดโม (ใบรับรองเดโมในตัว, มีลายน้ำ) หรือ PFX ที่เซ็นด้วยตนเอง.
-
อ่านใบรับรองจากการกำหนดค่า, ดังนั้นการเปลี่ยนแปลงมันไม่ต้องการการเปลี่ยนแปลงโค้ดเลย:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar signerSettings = builder.Configuration.GetSection("DoconutSigner"); builder.Services.AddDoconut(options => { options.LicensePath = "Doconut.Viewer.lic"; options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]), Password = signerSettings["Password"] ?? "", }); });เก็บ
.pfxไว้นอกwwwroot, และเก็บรหัสผ่านให้อยู่นอกappsettings.json: ความลับของผู้ใช้ในระหว่างการพัฒนา (dotnet user-secrets set "DoconutSigner:Password" "<password>"), ตัวแปรสภาพแวดล้อม (DoconutSigner__Password) หรือคลังข้อมูลในสภาพแวดล้อมการผลิต. -
ตรวจสอบบันทึกการเริ่มต้น. ควรอ่านว่า
using certificate '{subject}' (valid until …). Signatures are digitally sealed.คำเตือน; หากไม่ใช่หมายความว่าใบรับรองหมดอายุ, ยังไม่เป็นที่ใช้ได้, หรือไม่ได้ออกสำหรับการลงนามเอกสาร.
เชื่อถือในโปรแกรมอ่าน PDF. โปรแกรมอ่านจะแสดงลายเซ็นเป็นที่ถูกต้องเมื่อมันเชื่อถือรากของใบรับรอง. ด้วย PKI ขององค์กรของคุณ, สิ่งนี้จะใช้ได้กับทุกเครื่องที่เชื่อถือรากของคุณ, ซึ่งโดยปกติจะเป็นทุกเครื่องภายในองค์กร. ใบรับรองที่ Adobe เชื่อถือบนเครื่องใดก็ได้ (Adobe Approved Trust List) นั้น, ตามที่เราทราบ, ถูกออกโดยใช้คีย์ส่วนตัวบนโทเค็นฮาร์ดแวร์หรือ HSM, ซึ่งปลั๊กอินนี้ไม่สามารถใช้ได้: มันเซ็นจาก PFX เท่านั้น. ยืนยันกับผู้ให้บริการใบรับรองของคุณก่อนพึ่งพาการเชื่อมั่นแบบนี้.
ฟาร์มเว็บ
วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนโหนดที่ให้บริการ open. ภายหลังโหลดบาลานเซอร์โดยไม่มีเซสชันแบบ sticky, คำขอ run, download หรือการดูตัวอย่างในภายหลังอาจไปถึงโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสหนึ่งครั้ง, หลังจาก AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
store.FarmKey = farmKey; // อย่างน้อย 32 ไบต์, เหมือนกันบนทุกโหนด
// store.Ttl = TimeSpan.FromMinutes(30); // ระยะเวลาที่ไฟล์อัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});- เซิร์ฟเวอร์เดียวไม่ต้องการอะไร: หากไม่มีการเรียกนี้ที่เก็บในหน่วยความจำจะถูกใช้.
- การอัปโหลดและผลลัพธ์ถูกเข้ารหัสเมื่อพักอยู่บนแชร์ (AES-256, encrypt-then-MAC), และแต่ละไฟล์ถูกผูกกับโทเค็นของมัน, ดังนั้นโทเค็นหนึ่งจะไม่สามารถอ่านไฟล์ของโทเค็นอื่นได้.
FarmKeyต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยนArgumentExceptionเมื่อRootPathขาดหายหรือFarmKeyสั้นกว่า 32 ไบต์.- ตั้งค่า
RootPathให้ชี้ไปยังตำแหน่งที่แชร์เดียวกันที่ตัวดูแบบกระจายใช้, และให้ทุกโหนดใช้ใบรับรองการเซ็นเดียวกัน.
การอ้างอิง API
Facade และตัวเลือกของวิดเจ็ตอยู่ใน namespace Doconut; ประเภทของคำขอและผลลัพธ์อยู่ใน Doconut.Core.Models.Signing. SignerPlugin อยู่ใน Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}ได้รับการแก้ไขจากการฉีดพึ่งพา; ตัวสร้างเป็น internal. sourceExtension คือ ".pdf" หรือ ".docx". ภายใต้ใบอนุญาตแบบชำระเงิน cert จะถูกใช้และผลลัพธ์จะสะอาด; ภายใต้ใบอนุญาตชั่วคราว ใบรับรองสาธิตในตัวจะถูกใช้, cert จะถูกละเลย, และผลลัพธ์จะมีลายน้ำ.
SignRequest
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}ลายเซ็นที่มองเห็นได้หนึ่งครั้งที่วางไว้หนึ่งตำแหน่ง, พร้อมเมตาดาต้าของผู้ลงนามที่เป็นตัวเลือก.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes ไม่ว่างเปล่า
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes เป็น PNG สำหรับทุกประเภท. ลายเซ็นที่วาดหรือพิมพ์จะเป็นแบบโปร่งแสง; ภาพที่อัปโหลดจะคงความโปร่งแสงที่มีอยู่, ดังนั้น JPG ที่ทึบจะยังคงทึบ. Kind เป็นเพียงคำแนะนำ.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page มีค่าเริ่มจาก 1; X, Y, W และ H เป็น 0..1 ที่ทำให้เป็นมาตรฐานจากมุมบนซ้าย.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified เป็นค่าเริ่มต้น
public enum WordOutput { Pdf, Docx } // Pdf เป็นค่าเริ่มต้น; ถูกละเว้นสำหรับแหล่งที่มาของ PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);เอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, และนามสกุลของมันพร้อมจุด (".pdf" หรือ ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes ไม่ว่างเปล่า, หรือ PfxPath ไม่ว่าง
}ตั้งค่า PfxBytes หรือ PfxPath, พร้อมกับ Password.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}ตั้งค่าผ่าน DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียกต่อกันได้. ค่า null SigningCertificate หมายถึงใบรับรองสาธิตภายใต้ใบอนุญาตชั่วคราว, และลายเซ็น Visual จะใช้ได้เฉพาะใบอนุญาตแบบชำระเงิน.
การแก้ไขปัญหา
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
AddDoconut() โยน The Signer plugin is registered via AddPlugin but no active license grants Signer. | ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมัน | ติดตั้งใบอนุญาตที่ให้สิทธิ Signer, หรือเอา AddPlugin<SignerPlugin>() ออก |
AddDoconut() โยน AddSignerWidget() was called but the Signer plugin is not registered. | วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมัน | เพิ่ม options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() โยน Doconut Signer: the certificate file was not found at '{path}'. | PfxPath ชี้ไปที่ไฟล์ที่หายไป | แก้ไขเส้นทาง; ปรับใช้ไฟล์ในตำแหน่งที่บัญชีแอปสามารถอ่านได้ |
AddDoconut() โยน Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | รหัสผ่านผิด, หรือไม่ใช่ไฟล์ PKCS#12 | ตรวจสอบรหัสผ่าน; ใช้ .pfx จริง |
AddDoconut() โยน Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX ถูกส่งออกโดยไม่มีคีย์ส่วนตัว | ส่งออกอีกครั้งพร้อมคีย์ส่วนตัว |
การแก้ไข DocumentSigner โยน No IDocumentSigner is registered. | SignerPlugin ยังไม่ได้ลงทะเบียน | เพิ่ม AddPlugin<SignerPlugin>() ภายใน AddDoconut() |
| ผลลัพธ์มีลายน้ำ | ใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR) | ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer |
run ตอบ 400 No signing certificate configured. | ใบอนุญาตแบบชำระเงิน, โหมด Certified, และไม่มีใบรับรอง | ตั้งค่า SigningCertificate, หรือลงนามในโหมด Visual |
run ตอบ 400 The signing certificate expired on yyyy-MM-dd. | ใบรับรองหมดอายุ | เปลี่ยนใหม่; ลายเซ็น Visual ยังคงทำงานในระหว่างนี้ |
| บันทึกบอกว่าผลลัพธ์ "ใช้ใบรับรองสาธิตในตัว", แต่ใบอนุญาตแบบชำระเงินปฏิเสธลายเซ็น Certified | บรรทัดนั้นเขียนขึ้นเมื่อไม่มีการกำหนดค่าใบรับรอง, ไม่ว่าจะแบบใดก็ตาม | ตั้งค่า SigningCertificate |
วิดเจ็ตโหลดแล้วแต่บอกว่า Signing is not enabled on this server. | AddSignerWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับตำแหน่งที่ UseDoconut() ถูกเมานท์ | เรียก AddSignerWidget(); แก้ไข basePath |
run ตอบ 400 The signature image must be a PNG., Signature image is not valid base64. หรือ Signature image is too large. | UI ที่กำหนดเองส่ง URL data:, JPG, หรือมากกว่า MaxSignatureImageKb | ส่ง PNG base64 แบบไม่มีส่วนหัวภายในขีดจำกัด |
open ตอบ 413 File is too large. | การอัปโหลดเกิน MaxUploadMb | ยก MaxUploadMb ใน AddSignerWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์ |
run หรือ download ตอบ 404 Upload expired — please re-open the file. | ช่วงเวลา 30 นาทีหมดแล้ว, หรือโหนดเว็บฟาร์มไม่มีไฟล์อัปโหลด | เปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets |
ไฟล์ .docx ที่ลงนามแสดงไม่มีลายเซ็นในบางโปรแกรมดู | ผลลัพธ์ Word มีลายเซ็นแพ็กเกจ OOXML, ซึ่งโปรแกรมดูหลายตัวไม่แสดง | ลงนามเป็น PDF, ค่าเริ่มต้น |
| โปรแกรมอ่าน PDF บอกว่าตัวตนของผู้ลงนามไม่ทราบ | โปรแกรมอ่านไม่เชื่อถือรากของใบรับรอง (ใบรับรองสาธิตไม่มีวันได้รับความเชื่อถือ) | ใช้ใบรับรองจากรากที่โปรแกรมอ่านของคุณเชื่อถือ |
| วิดเจ็ตล้มเหลวเมื่อ UI อยู่บนต้นทางอื่น | endpoint ไม่มีการสนับสนุน CORS | ให้บริการ UI จากต้นทางเดียวกัน, หรือ reverse-proxy เส้นทาง Doconut |
| ธีมไม่ทำงาน | selector ชี้ไปยังองค์ประกอบภายใน mount | ชี้ไปยัง mount เอง: #host.dsw หรือ #host |
หน้านี้เป็นประโยชน์หรือไม่?