ปลั๊กอิน Signer
เซ็นเอกสาร PDF และ Word ด้วยลายเซ็นที่มองเห็นได้และตราดิจิทัล
ปลั๊กอิน Signer จะวางลายเซ็นที่มองเห็นได้บนเอกสารและโดยค่าเริ่มต้นจะปิดผนึกด้วยลายเซ็นดิจิทัลที่โปรแกรมอ่าน PDF สามารถตรวจสอบได้ มันเซ็นไฟล์ PDF และ Word (.docx) ลายเซ็นที่มองเห็นได้จะเป็นภาพ PNG เสมอ: วาด, พิมพ์, หรืออัปโหลดโดยผู้เซ็น
| ส่วน | ใช้เมื่อ |
|---|---|
DocumentSigner (C#) | คุณเซ็นบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
วิดเจ็ตแบบฝังตัว (doconutSigner.js) | คุณต้องการหน้าจออัปโหลด, เซ็นและดาวน์โหลดที่เตรียมไว้แล้วในหน้าของคุณ |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | คุณสร้าง UI การเซ็นของคุณเองโดยอ้างอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสาร |
ลายเซ็นแต่ละอันจะถูกวางเพียงครั้งเดียวบนหนึ่งหน้า ชื่อผู้เซ็น, เหตุผลและตำแหน่งสามารถเดินทางพร้อมกับมันได้
ติดตั้งแพคเกจ
Install-Package Doconut.NETFramework.Signerเพื่อผูกปลั๊กอินกับรุ่นที่เอกสารนี้อธิบาย:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0รักษาแพคเกจ Signer ให้เป็นเวอร์ชันเดียวกับ Doconut.NETFramework.
ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Signer.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; มันจะถูกอ่านพร้อมกับใบอนุญาตของ viewer.
ลงทะเบียนปลั๊กอิน
เช่นเดียวกับปลั๊กอิน Doconut ทุกตัว, Signer ลงทะเบียนกับ AddPlugin<TPlugin>() ใน DoconutHost.Initialize, ถูกเรียกจาก Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});เพิ่ม Doconut.DoconutHost.Shutdown() ไปยัง Application_End เพื่อให้งานเบื้องหลังหยุดอย่างสะอาดเมื่อแอปพูลรีไซเคิล
นั่นคือทั้งหมดที่ส่วนต่อประสาน C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddSignerWidget() (ดูที่ วิดเจ็ตแบบฝังตัว).
ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Signer. หากไม่มี, DoconutHost.Initialize จะโยนข้อผิดพลาดจาก Application_Start:
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.ใน System.Web นั่นหมายความว่าทุกคำขอจะตอบด้วย 500 ว่างเปล่า, และเหตุผลจะบันทึกไว้ใน Windows event log (source ASP.NET) เท่านั้น มันจะโยนข้อผิดพลาดเมื่อไม่มีใบอนุญาต, ไฟล์ TRIAL แบบเก่า, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่ใช้เกินช่วงเวอร์ชัน ดูที่ การตั้งค่าใบอนุญาต.
การให้ใบอนุญาตและลายน้ำ
| สถานะใบอนุญาต | การเริ่มต้น | ลายเซ็นที่รับรอง | ลายเซ็นภาพ |
|---|---|---|---|
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, กำหนดค่าใบรับรอง | เริ่มต้น | ปิดผนึกด้วยใบรับรองของคุณ, สะอาด (watermarked: false) | สะอาด |
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, ไม่มีใบรับรอง | เริ่มต้น | ปฏิเสธ: No signing certificate configured. | สะอาด |
| ใบอนุญาตแบบชำระเงิน, ใบรับรองหมดอายุหรือยังไม่ใช้ได้ | เริ่มต้น | ปฏิเสธ: The signing certificate expired on yyyy-MM-dd. | สะอาด |
| ใบอนุญาต Demo/NFR ชั่วคราว, ยังใช้งานหรือหมดอายุ | เริ่มต้น | ปิดผนึกด้วยใบรับรอง demo ที่สร้างไว้, มีลายน้ำ (watermarked: true) | มีลายน้ำ |
ไม่มีใบอนุญาต, ไฟล์ TRIAL แบบเก่า, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชัน | Application_Start โยนข้อผิดพลาด; ทุกคำขอตอบด้วย 500 ว่างเปล่า | — | — |
กฎนี้เหมือนกันสำหรับส่วนต่อประสาน C# และวิดเจ็ต: ผลลัพธ์จะมีลายน้ำเมื่อใบอนุญาตไม่ใช่ใบอนุญาต viewer แบบชำระเงินหรือเป็นแบบชั่วคราว ภายใต้ใบอนุญาตชั่วคราวปลั๊กอินจะเซ็นเสมอด้วยใบรับรอง demo ที่สร้างไว้, และใบรับรองใด ๆ ที่คุณกำหนดจะไม่ถูกใช้
ใบรับรอง demo สร้างตราที่แท้จริง, แต่โปรแกรมอ่าน PDF ไม่เชื่อถือมัน การบูรณาการสามารถสร้างและทดสอบแบบครบวงจรบนใบอนุญาตประเมินผล; เพื่อให้ได้ผลลัพธ์ที่สะอาดและเชื่อถือได้คุณต้องมีทั้งใบอนุญาตแบบชำระเงินและ ใบรับรองการเซ็น.
ใช้งานจาก C#
DocumentSigner ถูกลงทะเบียนโดย DoconutHost.Initialize; แก้ไขมันจาก DoconutHost.Services. ตัวสร้างของมันเป็น 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");
// Mode มีค่าเริ่มต้นเป็น Certified (ลายเซ็นที่มองเห็นได้ + ซีลดิจิทัล); 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, 81920, ct);
return output.ToArray();
}
}
}SignAsync รับสตรีมต้นทาง, ส่วนขยายของมัน (".pdf" หรือ ".docx"), คำขอ, และใบรับรอง สำหรับการเรียกนี้. ส่วนหุ้มไม่อ่าน SignerWidgetOptions.SigningCertificate; การตั้งค่านั้นเป็นสำหรับวิดเจ็ต. ส่ง null ภายใต้ใบอนุญาตทดลอง, หรือในโหมดแสดงผล.
SignResult เก็บเอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, พร้อมกับ Extension ของมัน (".pdf" หรือ ".docx") เพื่อให้คุณสามารถตั้งชื่อไฟล์ได้. คุณเป็นเจ้าของสตรีม: dispose มันเมื่อคุณทำเสร็จ.
ในคอนโทรลเลอร์ MVC 5
ทำให้แอคชันเป็นแบบไม่ประสานเวลาและ await ลายเซ็น. ตัวนี้จะทำการประทับลายเซ็นแบบแสดงผล, ซึ่งไม่ต้องการใบรับรอง:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}แหล่งข้อมูล Word จะถูกลงนามเป็น PDF เว้นแต่คุณขอผลลัพธ์เป็น Word. ตั้งชื่อผลลัพธ์จาก result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/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 แทนการคืนค่าเมื่อการเรียกไม่สำเร็จ:
| ข้อยกเว้น | ข้อความ | เมื่อ |
|---|---|---|
InvalidOperationException | No signing certificate configured. | โหมดรับรอง, ใบอนุญาตแบบชำระเงิน, และไม่มีการส่งใบรับรอง |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | โหมดรับรองพร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผลบังคับใช้ |
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 เลือกว่าลายเซ็นจะถูกปิดผนึกหรือไม่.
| โหมด | สิ่งที่สร้าง | ใบรับรอง | ตรวจสอบได้ |
|---|---|---|---|
SignatureMode.Certified (ค่าเริ่มต้น) | ลายเซ็นที่มองเห็นได้พร้อมกับตราประทับดิจิทัล | จำเป็นต้องมีใบอนุญาตแบบชำระเงิน | ใช่ |
SignatureMode.Visual | ลายเซ็นที่มองเห็นได้เท่านั้น | ไม่เคยต้องการ | ไม่: เป็นรูปภาพ |
ใช้ Certified เมื่อลายเซ็นต้องสามารถพิสูจน์ได้: การอนุมัติ, สัญญา, หรือสิ่งใดที่ผู้ตรวจสอบต้องตรวจสอบเพื่อยืนยันตัวตนและความสมบูรณ์ ใช้ Visual เมื่อคุณต้องการเพียงรูปลักษณ์ของลายเซ็น, หรือไม่มีใบรับรอง ใบอนุญาตชั่วคราวจะใส่ลายน้ำให้ทั้งสองแบบ
ตรา PDF เป็นลายเซ็นแยก 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. ให้ทั้งไบต์หรือพาธ, พร้อมรหัสผ่าน App_Data เป็นตำแหน่งที่ดีสำหรับไฟล์นี้, เนื่องจาก IIS ไม่เคยให้บริการมัน:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});คุณสมบัติของ SigningCertificate เป็นแบบ init-only, ซึ่ง C# 7.3 (ค่าเริ่มต้นสำหรับโครงการ .NET Framework) ไม่สามารถตั้งค่าได้ ตั้งค่า <LangVersion> เป็น 9.0 หรือเวอร์ชันใหม่กว่าในไฟล์โครงการ.
ใบรับรองจะถูกเก็บไว้ในหน่วยความจำเท่านั้น ไม่เคยบันทึก, ส่งกลับไปยังไคลเอนต์, หรือเก็บถาวร, และรหัสผ่านจะไม่ปรากฏในข้อความแสดงข้อผิดพลาด.
ข้อกำหนด:
- ชุด PFX / PKCS#12 พร้อมคีย์ส่วนตัว. ไฟล์ที่มีเฉพาะคีย์สาธารณะ (
.cer,.crt) ไม่สามารถลงนามได้ ส่งออกสายโซ่ผู้ออกพร้อมกับมัน, เพื่อให้ตรา PDF สามารถบรรจุได้ - รหัสผ่านที่ถูกต้อง.
- อยู่ภายใน ช่วงเวลาที่มีผล ของใบรับรอง. ใบรับรองที่หมดอายุหรือยังไม่ถึงวันเริ่มใช้จะไม่ทำให้แอปหยุดทำงาน, แต่ลายเซ็น Certified จะถูกปฏิเสธจนกว่าจะเปลี่ยนใหม่. ลายเซ็น Visual จะไม่ได้รับผลกระทบ.
- ออกเพื่อการลงนามเอกสาร: การใช้คีย์ที่มี digital signature หรือ non-repudiation, และการใช้คีย์ขยาย, หากมี, ที่อนุญาตให้ลงนามเอกสาร, ปกป้องอีเมล หรือการตรวจสอบตัวตนของไคลเอนต์. ใบรับรองที่ออกเพื่อวัตถุประสงค์อื่น, เช่น ใบรับรองเซิร์ฟเวอร์ TLS, ยังสามารถลงนามได้, แต่โปรแกรมอ่าน 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 จะถูกตรวจสอบหนึ่งครั้ง ภายใน DoconutHost.Initialize ดังนั้น PFX ที่กำหนดค่าไม่ถูกต้องจะล้มเหลวที่การเริ่มต้นแทนที่จะเกิดขึ้นที่ลายเซ็นแรก ปัญหา 3 รายการจะทำให้เกิด InvalidOperationException จาก Application_Start และทุกคำขอจะตอบกลับด้วย 500 ว่าง; ข้อความนี้อยู่ในบันทึกเหตุการณ์ของ Windows:
| ข้อความ | วิธีแก้ |
|---|---|
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 อีกครั้งพร้อมกับคีย์ส่วนตัว |
บน ASP.NET Core โฮสต์จะบันทึกบรรทัดหนึ่งที่การเริ่มต้นโดยระบุชื่อใบรับรอง หรือเตือนว่าใบรับรองหมดอายุหรือไม่ได้ออกสำหรับการลงนาม DoconutHost จะไม่เขียนบรรทัดนั้น ดังนั้นบน .NET Framework ให้ตรวจสอบใบรับรองใหม่โดยการลงนามเอกสารทดสอบในโหมด Certified.
ส่วนหน้าของ C# จะไม่ถูกตรวจสอบที่การเริ่มต้น ใบรับรองที่คุณส่งให้ SignAsync จะถูกอ่านเมื่อคุณลงนาม ดังนั้นเส้นทางหรือรหัสผ่านที่ผิดจะทำให้การเรียกนั้นล้มเหลว.
วิดเจ็ตแบบ Drop-in
เปิดใช้งาน endpoint
endpoint ?sign=open|run|download ของวิดเจ็ตให้บริการโดย DocImage.axd และ ปิดโดยค่าเริ่มต้น เปิดใช้งานพวกมันข้างๆ การลงทะเบียนปลั๊กอิน:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // ค่าเริ่มต้น
widget.MaxSignatureImageKb = 512; // ค่าเริ่มต้น
// widget.SigningCertificate: ดูการตั้งค่า Certificate; ปล่อยให้เป็น null สำหรับการลงนาม demo (มีลายน้ำ)
});
});
// System.Web อ่านข้อมูลอัปโหลดทั้งหมดก่อนที่ Doconut จะเห็นมัน: รักษา maxRequestLength (KB) และ
// maxAllowedContentLength (bytes) ใน Web.config อยู่เหนือ MaxUploadMb ของ widget.AddSignerWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น มันไม่ได้ให้สิทธิ์การลงนามโดยตัวเอง: ต้องการ AddPlugin<SignerPlugin>(), หรือ DoconutHost.Initialize จะโยนข้อผิดพลาด:
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.endpoint และสคริปต์จะให้บริการโดย handler และโมดูลที่ลงทะเบียนใน Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>โมดูลให้บริการสคริปต์ไม่ว่าจะวิดเจ็ตเปิดใช้งานหรือไม่ กรณีไม่มี AddSignerWidget(), วิดเจ็ตจะโหลดและวาดโซนดรอปของมัน, และคำขอแรกของมันจะตอบกลับด้วย 404: จากนั้นวิดเจ็ตจะรายงาน Signing is not enabled on this server.
ขีดจำกัดการอัปโหลด
ASP.NET จะอ่านเนื้อหาคำขอทั้งหมดก่อนที่ DocImage.axd จะทำงาน การอัปโหลดที่เกิน MaxUploadMb แต่ต่ำกว่าขีดจำกัดของโฮสต์จะได้รับ JSON ของวิดเจ็ตเอง 413 (File is too large.). การอัปโหลดที่เกินขีดจำกัดของโฮสต์จะถูก IIS ปฏิเสธก่อนด้วยหน้าข้อผิดพลาดที่วิดเจ็ตไม่สามารถอ่านได้ ให้รักษาขีดจำกัดของโฮสต์ทั้งสองให้สูงกว่าขีดจำกัดของวิดเจ็ต:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>การอัปโหลดที่ส่งโดยไม่มี Content-Length (chunked) ซึ่งเกินขีดจำกัดของโฮสต์ก็จะได้รับหน้าข้อผิดพลาดของ IIS; ไม่มีวิธีแก้สำหรับกรณีนั้น.
ฝังลง
สคริปต์ให้บริการที่ /doconut-res/js/doconutSigner.js. มันเป็นไฟล์เดียวที่รวมทุกอย่างไว้โดยไม่มีการพึ่งพาใด ๆ. ตั้งค่า basePath ให้ชี้ไปที่ตัวจัดการ:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) รับตัวเลือก CSS หรือองค์ประกอบ, จะโยนข้อผิดพลาดหากไม่พบ mount, และคืนค่า handle. ค่าเริ่มต้นของ widget basePath, /doconut, คือ endpoint ของ ASP.NET Core; ในแพ็คเกจนี้ต้องเป็น '/DocImage.axd'.
ผู้ลงนามอัปโหลดไฟล์ PDF หรือไฟล์ .docx, สร้างลายเซ็น (Draw บนแคนวาส, Type ชื่อในฟอนต์ลายเซ็น, หรือ Image จาก PNG, JPG หรือ GIF), ลากและปรับขนาดบนหน้า, แล้วลงนามและดาวน์โหลดผลลัพธ์. widget จะส่งลายเซ็นเป็น PNG เสมอ; ภาพที่อัปโหลดจะถูกแปลงในเบราว์เซอร์เป็น PNG ที่มีขนาด 520×160.
ตัวเลือก
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | '/doconut' | ที่ที่ endpoint ?sign= และภาพตัวอย่างถูกให้บริการ. ตั้งค่า '/DocImage.axd' บนแพ็คเกจนี้ |
resPath | string | '/doconut-res' | สงวนไว้; widget มี CSS ของตัวเองรวมอยู่ |
maxUploadMb | number | 25 | ตรวจสอบเฉพาะด้านไคลเอนต์, ดังนั้นไฟล์ที่ใหญ่เกินจะล้มเหลวเร็ว. ขีดจำกัดของเซิร์ฟเวอร์คือ MaxUploadMb ใน AddSignerWidget |
maxSignatureKb | number | 512 | ขีดจำกัดด้านไคลเอนต์สำหรับโหมด Image. ให้เท่ากับ MaxSignatureImageKb ของเซิร์ฟเวอร์ |
previewWidth | number | 560 | ความกว้างพิกเซลของภาพตัวอย่างหน้า |
licenseUrl | string | null | null | เปลี่ยนข้อความลายน้ำเดโมเป็นลิงก์ไปยัง URL นี้ |
signatureMode | string | 'certified' | ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าอื่นใดจะกลายเป็น 'certified' |
showSignatureModeToggle | boolean | true | แสดงตัวเลือก Digital signature / Visual only. เมื่อใช้ false, widget จะลงนามด้วย signatureMode |
wordOutput | string | 'pdf' | ผลลัพธ์เริ่มต้นสำหรับแหล่งข้อมูล .docx: 'pdf' หรือ 'docx'. ค่าอื่นใดจะกลายเป็น 'pdf' |
showOutputFormatToggle | boolean | true | แสดงตัวเลือก PDF / Word, เฉพาะแหล่งข้อมูล .docx. เมื่อใช้ false, widget จะใช้ wordOutput |
labels | object | {} | เขียนทับส่วนใดส่วนหนึ่งของข้อความภาษาอังกฤษ |
การซ่อนสวิตช์ไม่ได้ปิดการทำงานของฟีเจอร์; มันกำหนดค่าคงที่. มีการกำหนดค่าที่พบบ่อยสองแบบ:
// แสดงสวิตช์ทั้งสอง, ลายเซ็นดิจิทัลเป็นค่าเริ่มต้น: ผู้ลงนามแบบเซลฟ์เซอร์วิสเต็มรูปแบบ.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// แสดงผลอย่างเดียว, ไม่มีสวิตช์: ตราประทับแบบง่ายที่ไม่มีลายเซ็นดิจิทัล.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});คอลแบ็ก
| คอลแบ็ก | เกิดขึ้นเมื่อ | ข้อมูล |
|---|---|---|
onReady | ครั้งเดียว, ที่การ mount (ไม่ซ้ำเมื่อ reset()) | — |
onSourceLoaded | ไฟล์ถูกเปิดและแสดงตัวอย่าง | { file: { token, name, pages, ext } } |
onSigned | การลงนามสำเร็จ | { downloadToken, downloadName, watermarked } |
onDownload | เมื่อคลิกดาวน์โหลดแต่ละครั้ง | { downloadName, downloadToken } |
onError | ขั้นตอนเปิด, ลงนาม หรือดาวน์โหลดล้มเหลว, หรือไฟล์โหมด Image มีขนาดใหญ่เกิน | { message } |
คอลแบ็กที่โยนข้อยกเว้นจะถูกจับและบันทึก; มันไม่ทำให้กระบวนการของ widget หยุดทำงาน.
ตัวจัดการเชิงบังคับ
| เมธอด | พฤติกรรม |
|---|---|
reset() | คืนค่าไปยังหน้าจอดรอปและล้างกระบวนการปัจจุบัน. จะไม่เรียก onReady อีก. ไม่ทำอะไรหลังจาก destroy() |
loadFile(file) | เริ่มกระบวนการด้วย File. ไม่ทำอะไรหาก widget ไม่อยู่ที่หน้าจอดรอป; เรียก reset() ก่อนหากจำเป็น |
destroy() | ลบ listener, ทำให้ mount ว่างเปล่า, และทำให้ instance ค้าง |
const signerWidget = Doconut.signer('#host', {
basePath: '/DocImage.axd',
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'.
| Key | English default |
|---|---|
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 ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ 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 นี้บน DocImage.axd. เส้นทางตอบกลับ 404 จนกว่า AddSignerWidget() จะถูกเรียก. ข้อผิดพลาดมีเนื้อหา JSON, { "error": "..." }, ยกเว้นกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?sign= จะตอบกลับ 400.
| Route | Purpose | Success response |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | อัปโหลด PDF หรือ .docx และเปิดเพื่อดูตัวอย่าง | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | เซ็นไฟล์ที่อัปโหลด | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | สตรีมไฟล์ที่เซ็นแล้ว | 200 — ไฟล์, Content-Disposition: attachment, Cache-Control: no-store |
ext ในการตอบสนอง open จะรวมจุดนำหน้า (".docx"). การแสดงตัวอย่างหน้าใช้เส้นทางภาพผู้ชมมาตรฐาน, /DocImage.axd?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"
}| Field | Notes |
|---|---|
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 | ไม่บังคับ. แต่ละค่าจะถูกตัด trim, ค่าว่างจะถูกละเว้น, และแต่ละค่าจะถูกตัดที่ 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.
| Route | Status | When | Body |
|---|---|---|---|
| any | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน | เฉพาะสถานะ |
| any | 405 | คำกริยาผิด (open และ run ต้องการ POST, download ต้องการ GET) | เฉพาะสถานะ |
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 (แต่ไม่เกินขีดจำกัดของ IIS) | 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 | เฉพาะสถานะ |
download | 404 | โทเคนไม่รู้จักหรือหมดอายุ | เฉพาะสถานะ |
การเดินทางรอบสมบูรณ์ด้วย fetch:
// file: ไฟล์ที่ต้องเซ็น; pngBase64: ลายเซ็นในรูปแบบ base64 PNG แบบเปล่า, โดยไม่มีคำนำหน้า data:,
// เช่น canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 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);
}The endpoints are same-origin: เวอร์ชันนี้ไม่มีการสนับสนุน CORS. ให้บริการ UI ของคุณและสคริปต์วิดเจ็ตจากต้นทางเดียวกันกับแอปพลิเคชัน, หรือทำ reverse-proxy DocImage.axd และ /doconut-res ภายใต้ต้นทางของ UI ของคุณ.
ในสภาพการผลิต
-
ติดตั้งปลั๊กอิน ถัดจากแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน:
Install-Package Doconut.NETFramework.Signer. -
เพิ่มไฟล์ใบอนุญาต. วาง
Doconut.Viewer.Signer.licในโฟลเดอร์เดียวกันกับDoconut.Viewer.lic. -
รับใบรับรองของคุณเป็น PFX พร้อมคีย์ส่วนตัวและสายการออกใบรับรอง, จากหน่วยงานออกใบรับรองหรือ PKI ขององค์กรของคุณ. เพื่อทดลองก่อน, ใช้ใบอนุญาตเดโม (ใบรับรองเดโมในตัว, มีลายน้ำ) หรือ PFX ที่ลงนามด้วยตนเอง.
-
อ่านใบรับรองจากการกำหนดค่า, เพื่อให้การเปลี่ยนแปลงไม่ต้องแก้ไขโค้ด:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });เก็บ
.pfxไว้ในApp_Data, ซึ่ง IIS จะไม่ให้บริการ, และเก็บรหัสผ่านให้อยู่ไกลจากWeb.configธรรมดา: ใช้ส่วนการกำหนดค่าที่เข้ารหัส, หรือที่เก็บความลับที่การปรับใช้ของคุณอ่าน. -
ลงนามเอกสารทดสอบในโหมด Certified. ใบรับรองที่หมดอายุหรือยังไม่ถึงวันใช้งานจะถูกปฏิเสธด้วย
The signing certificate expired on yyyy-MM-dd.(หรือis not valid before), และโปรแกรมอ่าน PDF จะแสดงว่ามันเชื่อถือลายเซ็นหรือไม่.
ความเชื่อถือในโปรแกรมอ่าน PDF. โปรแกรมอ่านจะแสดงลายเซ็นเป็นที่ถูกต้องเมื่อมันเชื่อถือรากของใบรับรอง. ด้วย PKI ขององค์กรของคุณ, สิ่งนี้จะเป็นจริงบนทุกเครื่องที่เชื่อถือรากของคุณ, ซึ่งโดยปกติคือทุกเครื่องภายในองค์กร. ใบรับรองที่ Adobe เชื่อถือบนเครื่องใดก็ได้ (Adobe Approved Trust List) นั้น, ตามที่เราทราบ, ถูกออกด้วยคีย์ส่วนตัวบนโทเค็นฮาร์ดแวร์หรือ HSM, ซึ่งปลั๊กอินนี้ไม่สามารถใช้ได้: มันลงนามจาก PFX เท่านั้น. ยืนยันกับผู้ให้บริการใบรับรองของคุณก่อนพึ่งพาความเชื่อถือแบบนี้.
ฟาร์มเว็บ
วิดเจ็ตจะเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนเซิร์ฟเวอร์ที่ให้บริการ open. อยู่เบื้องหลังโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือการพรีวิวในภายหลังอาจไปถึงเซิร์ฟเวอร์อื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสผ่านอาร์กิวเมนต์ที่สองของ DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => 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);
}ได้รับการแก้ไขจาก DoconutHost.Services; ตัวสร้างเป็น 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 และ 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 และ 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 ไม่เป็นค่าว่าง
}ตั้งค่า either PfxBytes หรือ PfxPath, พร้อมกับ Password. ตัวตั้งค่าเป็นแบบ init-only: โครงการต้องใช้ C# 9.0 หรือใหม่กว่า.
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 จะใช้ได้เฉพาะในลิขสิทธิ์ที่ชำระเงิน.
การแก้ไขปัญหา
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
ทุกคำขอตอบกลับเป็น 500 ว่างเปล่าหลังจากเพิ่มปลั๊กอิน; บันทึกเหตุการณ์แสดง The Signer plugin is registered via AddPlugin but no active license grants Signer. | ไม่มีลิขสิทธิ์, ไฟล์ TRIAL, ลิขสิทธิ์ที่ไม่มี Signer, หรือ ลิขสิทธิ์ที่ชำระเงินที่อยู่นอกช่วงเวอร์ชัน | ติดตั้งลิขสิทธิ์ที่ให้สิทธิ Signer, หรือเอา AddPlugin<SignerPlugin>() ออก |
บันทึกเหตุการณ์แสดง AddSignerWidget() was called but the Signer plugin is not registered. | วิดเจ็ตเปิดใช้งานโดยไม่มีปลั๊กอินของมัน | เพิ่ม options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
บันทึกเหตุการณ์แสดง Doconut Signer: the certificate file was not found at '{path}'. | PfxPath ชี้ไปที่ไฟล์ที่หายไป | แก้ไขเส้นทาง; ปรับใช้ไฟล์ในตำแหน่งที่บัญชีของ app pool สามารถอ่านได้ |
บันทึกเหตุการณ์แสดง Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | รหัสผ่านผิด, หรือไม่ใช่ไฟล์ PKCS#12 | ตรวจสอบรหัสผ่าน; ใช้ .pfx จริง |
บันทึกเหตุการณ์แสดง Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | ไฟล์ PFX ถูกส่งออกโดยไม่มีคีย์ส่วนตัว | ส่งออกอีกครั้งพร้อมคีย์ส่วนตัว |
new SigningCertificate { … } ไม่สามารถคอมไพล์ได้ | โครงการใช้ C# 7.3, ซึ่งไม่สามารถตั้งค่า init-only properties | ตั้งค่า <LangVersion> เป็น 9.0 หรือใหม่กว่า |
การแก้ไข DocumentSigner ทำให้เกิดข้อผิดพลาด No IDocumentSigner is registered. | SignerPlugin ไม่ได้ลงทะเบียน | เพิ่ม AddPlugin<SignerPlugin>() ใน DoconutHost.Initialize |
| ผลลัพธ์มีลายน้ำ | ลิขสิทธิ์เป็นชั่วคราว (Demo/NFR) | ใช้ลิขสิทธิ์ที่ชำระเงินที่ให้สิทธิ Signer |
run ตอบกลับ 400 No signing certificate configured. | ลิขสิทธิ์ที่ชำระเงิน, โหมด Certified, และไม่มีใบรับรอง | กำหนดค่า SigningCertificate, หรือลงนามในโหมด Visual |
run ตอบกลับ 400 The signing certificate expired on yyyy-MM-dd. | ใบรับรองหมดอายุ | เปลี่ยนใหม่; ลายเซ็น Visual จะยังทำงานต่อไปในระหว่างนี้ |
วิดเจ็ตโหลดแต่แสดงข้อความ Signing is not enabled on this server. | AddSignerWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่เป็น '/DocImage.axd' | เรียก AddSignerWidget(); ตั้งค่า basePath: '/DocImage.axd' |
| การอัปโหลดขนาดใหญ่แสดงหน้าแสดงข้อผิดพลาด IIS แทนข้อความของวิดเจ็ต | maxRequestLength / maxAllowedContentLength ต่ำกว่า MaxUploadMb | เพิ่มขีดจำกัดของโฮสต์ทั้งสองให้สูงกว่า MaxUploadMb |
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 DocImage.axd และ /doconut-res |
| ธีมไม่ทำงาน | selector ชี้ไปที่องค์ประกอบภายใน mount | ชี้ไปที่ mount เอง: #host.dsw หรือ #host |
หมายเหตุของ Framework
เมื่อเทียบกับแพ็กเกจ ASP.NET Core, แพ็กเกจนี้แตกต่างกันเฉพาะด้านการโฮสต์; API, สัญญา endpoint, สคริปต์วิดเจ็ตและกฎการให้สิทธิ์นั้นเหมือนกัน.
- การลงทะเบียน อยู่ใน
Application_Start, ผ่านDoconutHost.Initialize, แทนที่จะเป็นbuilder.Services.AddDoconut. บริการเช่นAddDoconutDistributedWidgetsจะอยู่ในอาร์กิวเมนต์ที่สองของมัน. - จุดสิ้นสุด ถูกให้บริการโดย
DocImage.axdและสคริปต์โดยDoconutResourceModule, ทั้งสองลงทะเบียนในWeb.config, แทนที่จะเป็นUseDoconut()และUseDoconutResources(). วิดเจ็ตต้องการbasePath: '/DocImage.axd'. - ข้อผิดพลาดการเริ่มต้น ปรากฏเป็น
500ว่างเปล่าบนทุกคำขอ, โดยสาเหตุจะอยู่ในบันทึกเหตุการณ์ของ Windows. - การอัปโหลด ถูกอ่านเต็มโดย ASP.NET ก่อนที่ Doconut จะเห็น, ดังนั้นขีดจำกัดของ IIS ต้องสูงกว่า
MaxUploadMb. - ไม่มีบรรทัดบันทึกการเริ่มต้น เกี่ยวกับใบรับรอง: ข้อผิดพลาดใบรับรองสามข้อยังคงถูกโยนออก, แต่บรรทัดที่ระบุชื่อใบรับรองไม่ได้ถูกเขียน.
- C# 9.0 หรือใหม่กว่า จำเป็นต้องใช้เพื่อกำหนดคุณสมบัติ init-only ของ
SigningCertificate. - เฉพาะ Windows, เช่นเดียวกับส่วนที่เหลือของแพ็กเกจ .NET Framework.
หน้านี้เป็นประโยชน์หรือไม่?