ปลั๊กอิน Signer

เซ็นเอกสาร PDF และ Word ด้วยลายเซ็นที่มองเห็นได้และตราดิจิทัล

ปลั๊กอิน Signer จะวางลายเซ็นที่มองเห็นได้บนเอกสารและโดยค่าเริ่มต้นจะปิดผนึกด้วยลายเซ็นดิจิทัลที่โปรแกรมอ่าน PDF สามารถตรวจสอบได้ มันเซ็นไฟล์ PDF และ Word (.docx) ลายเซ็นที่มองเห็นได้จะเป็นภาพ PNG เสมอ: วาด, พิมพ์, หรืออัปโหลดโดยผู้เซ็น

ส่วนใช้เมื่อ
DocumentSigner (C#)คุณเซ็นบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง
วิดเจ็ตแบบฝังตัว (doconutSigner.js)คุณต้องการหน้าจออัปโหลด, เซ็นและดาวน์โหลดที่เตรียมไว้แล้วในหน้าของคุณ
HTTP endpoints on DocImage.axd (?sign=open|run|download)คุณสร้าง UI การเซ็นของคุณเองโดยอ้างอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสาร

ลายเซ็นแต่ละอันจะถูกวางเพียงครั้งเดียวบนหนึ่งหน้า ชื่อผู้เซ็น, เหตุผลและตำแหน่งสามารถเดินทางพร้อมกับมันได้

ติดตั้งแพคเกจ

powershell
Install-Package Doconut.NETFramework.Signer

เพื่อผูกปลั๊กอินกับรุ่นที่เอกสารนี้อธิบาย:

powershell
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:

csharp
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:

text
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>().

csharp
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 ลายเซ็น. ตัวนี้จะทำการประทับลายเซ็นแบบแสดงผล, ซึ่งไม่ต้องการใบรับรอง:

csharp
[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:

csharp
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 แทนการคืนค่าเมื่อการเรียกไม่สำเร็จ:

ข้อยกเว้นข้อความเมื่อ
InvalidOperationExceptionNo signing certificate configured.โหมดรับรอง, ใบอนุญาตแบบชำระเงิน, และไม่มีการส่งใบรับรอง
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.โหมดรับรองพร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผลบังคับใช้
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.ไบต์ PNG ว่างเปล่า, หรือการวางตำแหน่งที่ไม่ถูกต้อง
NotSupportedExceptionThe 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 ไม่เคยให้บริการมัน:

csharp
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"] ?? "",
        };
    });
});
csharp
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:

bash
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 และ ปิดโดยค่าเริ่มต้น เปิดใช้งานพวกมันข้างๆ การลงทะเบียนปลั๊กอิน:

csharp
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 จะโยนข้อผิดพลาด:

text
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:

xml
<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 ปฏิเสธก่อนด้วยหน้าข้อผิดพลาดที่วิดเจ็ตไม่สามารถอ่านได้ ให้รักษาขีดจำกัดของโฮสต์ทั้งสองให้สูงกว่าขีดจำกัดของวิดเจ็ต:

xml
<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 ให้ชี้ไปที่ตัวจัดการ:

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

ตัวเลือก

ตัวเลือกประเภทค่าเริ่มต้นหมายเหตุ
basePathstring'/doconut'ที่ที่ endpoint ?sign= และภาพตัวอย่างถูกให้บริการ. ตั้งค่า '/DocImage.axd' บนแพ็คเกจนี้
resPathstring'/doconut-res'สงวนไว้; widget มี CSS ของตัวเองรวมอยู่
maxUploadMbnumber25ตรวจสอบเฉพาะด้านไคลเอนต์, ดังนั้นไฟล์ที่ใหญ่เกินจะล้มเหลวเร็ว. ขีดจำกัดของเซิร์ฟเวอร์คือ MaxUploadMb ใน AddSignerWidget
maxSignatureKbnumber512ขีดจำกัดด้านไคลเอนต์สำหรับโหมด Image. ให้เท่ากับ MaxSignatureImageKb ของเซิร์ฟเวอร์
previewWidthnumber560ความกว้างพิกเซลของภาพตัวอย่างหน้า
licenseUrlstring | nullnullเปลี่ยนข้อความลายน้ำเดโมเป็นลิงก์ไปยัง URL นี้
signatureModestring'certified'ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าอื่นใดจะกลายเป็น 'certified'
showSignatureModeTogglebooleantrueแสดงตัวเลือก Digital signature / Visual only. เมื่อใช้ false, widget จะลงนามด้วย signatureMode
wordOutputstring'pdf'ผลลัพธ์เริ่มต้นสำหรับแหล่งข้อมูล .docx: 'pdf' หรือ 'docx'. ค่าอื่นใดจะกลายเป็น 'pdf'
showOutputFormatTogglebooleantrueแสดงตัวเลือก PDF / Word, เฉพาะแหล่งข้อมูล .docx. เมื่อใช้ false, widget จะใช้ wordOutput
labelsobject{}เขียนทับส่วนใดส่วนหนึ่งของข้อความภาษาอังกฤษ

การซ่อนสวิตช์ไม่ได้ปิดการทำงานของฟีเจอร์; มันกำหนดค่าคงที่. มีการกำหนดค่าที่พบบ่อยสองแบบ:

javascript
// แสดงสวิตช์ทั้งสอง, ลายเซ็นดิจิทัลเป็นค่าเริ่มต้น: ผู้ลงนามแบบเซลฟ์เซอร์วิสเต็มรูปแบบ.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// แสดงผลอย่างเดียว, ไม่มีสวิตช์: ตราประทับแบบง่ายที่ไม่มีลายเซ็นดิจิทัล.
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 ค้าง
javascript
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'.

KeyEnglish default
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

คีย์เพิ่มเติมครอบคลุมขั้นตอนการวางตำแหน่ง, หน้าจอข้อผิดพลาด, แบบฟอร์มที่เชื่อมโยงของประกาศสาธิต (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) และประกาศ aria-live.

เมื่อ open หรือ run ตอบกลับ 404 โดยไม่มีข้อผิดพลาด JSON, วิดเจ็ตจะแสดง signingNotEnabled. ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะมีลำดับความสำคัญสูงสุด, ดังนั้นข้อความเช่นการอัปโหลดที่หมดอายุจะยังคงแสดงอยู่.

การกำหนดธีม

วิดเจ็ตจะเพิ่มคลาส dsw ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS แบบกำหนดเอง, ดังนั้นคุณสามารถกำหนดธีมได้โดยไม่ต้องแก้ไขภายใน:

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.

RoutePurposeSuccess 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:

json
{
  "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"
}
FieldNotes
tokenโทเคนจาก open
signature.kindDrawn, Typed หรือ Image, ไม่สนใจตัวพิมพ์ใหญ่/เล็ก; อย่างอื่นจะกลายเป็น Drawn. คำแนะนำเท่านั้น: payload จะเป็น PNG เสมอ
signature.payloadPNG base64 แบบไม่มีส่วนหัว data:. ต้องเป็น PNG จริงและขนาดไม่เกิน MaxSignatureImageKb หลังจากถอดรหัส
placement.pageเริ่มจาก 1
placement.x / y / w / hNormalized 0..1 จากมุมบนซ้าย, พร้อมกับ x + w ≤ 1 และ y + h ≤ 1
meta.signerName / reason / locationไม่บังคับ. แต่ละค่าจะถูกตัด trim, ค่าว่างจะถูกละเว้น, และแต่ละค่าจะถูกตัดที่ 256 ตัวอักษร
wordOutputpdf (ค่าเริ่มต้น) หรือ docx; ไม่สนใจสำหรับแหล่ง PDF. อย่างอื่นจะกลายเป็น pdf
modecertified (ค่าเริ่มต้น) หรือ visual. อย่างอื่นจะกลายเป็น certified

downloadName ตามผลลัพธ์: <source>-signed.pdf หรือ <source>-signed.docx, และ download ส่ง Content-Type ที่ตรงกัน.

ไฟล์ต้นฉบับที่อัปโหลดและผลลัพธ์ที่เซ็นจะถูกเก็บไว้แต่ละ 30 นาที. หลังจากนั้น, run และ download จะตอบกลับ 404 และไฟล์ต้องเปิดใหม่อีกครั้ง. โทเคนทั้งหมดเป็น GUID.

RouteStatusWhenBody
any404วิดเจ็ตไม่ได้เปิดใช้งานเฉพาะสถานะ
any405คำกริยาผิด (open และ run ต้องการ POST, download ต้องการ GET)เฉพาะสถานะ
open400ไม่ใช่การอัปโหลดแบบ multipartExpected a multipart file upload.
open400ไม่มีไฟล์ หรือไฟล์ว่างNo file uploaded.
open400ค่าอื่นใดนอกจาก .pdf หรือ .docxSigning supports PDF and Word (.docx) files only.
open413การอัปโหลดเกิน MaxUploadMb (แต่ไม่เกินขีดจำกัดของ IIS)File is too large.
run400เนื้อหาไม่เป็น JSON ที่ถูกต้อง หรือว่างเปล่าMalformed request. / Empty request.
run400โทเคนหายไปหรือไม่ใช่ GUIDInvalid token.
run404การอัปโหลดหมดอายุหรือไม่เคยเปิดUpload expired — please re-open the file.
run400ไม่มีลายเซ็น หรือไม่มีการวางตำแหน่งNo signature supplied. / No placement supplied.
run400payload ไม่ใช่ base64, ว่างเปล่า, ขนาดใหญ่เกินไป, หรือไม่ใช่ PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400การวางตำแหน่งอยู่นอกหน้าThe signature or its placement is invalid.
run400โหมดรับรอง, มีใบอนุญาตแบบชำระเงินและไม่มีใบรับรองNo signing certificate configured.
run400โหมดรับรองพร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผลThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500การประมวลผลล้มเหลวA sanitized message
download400โทเคนหายไปหรือไม่ใช่ GUIDเฉพาะสถานะ
download404โทเคนไม่รู้จักหรือหมดอายุเฉพาะสถานะ

การเดินทางรอบสมบูรณ์ด้วย fetch:

javascript
// 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 ของคุณ.

ในสภาพการผลิต

  1. ติดตั้งปลั๊กอิน ถัดจากแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน: Install-Package Doconut.NETFramework.Signer.

  2. เพิ่มไฟล์ใบอนุญาต. วาง Doconut.Viewer.Signer.lic ในโฟลเดอร์เดียวกันกับ Doconut.Viewer.lic.

  3. รับใบรับรองของคุณเป็น PFX พร้อมคีย์ส่วนตัวและสายการออกใบรับรอง, จากหน่วยงานออกใบรับรองหรือ PKI ขององค์กรของคุณ. เพื่อทดลองก่อน, ใช้ใบอนุญาตเดโม (ใบรับรองเดโมในตัว, มีลายน้ำ) หรือ PFX ที่ลงนามด้วยตนเอง.

  4. อ่านใบรับรองจากการกำหนดค่า, เพื่อให้การเปลี่ยนแปลงไม่ต้องแก้ไขโค้ด:

    xml
    <appSettings>
      <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" />
    </appSettings>
    csharp
    var 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 ธรรมดา: ใช้ส่วนการกำหนดค่าที่เข้ารหัส, หรือที่เก็บความลับที่การปรับใช้ของคุณอ่าน.

  5. ลงนามเอกสารทดสอบในโหมด 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:

csharp
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

csharp
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

csharp
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

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes ไม่ว่างเปล่า
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes เป็น PNG สำหรับทุกประเภท. ลายเซ็นที่วาดหรือพิมพ์จะเป็นแบบโปร่งแสง; ภาพที่อัปโหลดจะรักษาความโปร่งแสงที่มีอยู่, ดังนั้น JPG ที่ทึบจะยังคงทึบ. Kind เป็นเพียงคำแนะนำ.

SignaturePlacement

csharp
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

csharp
public enum SignatureMode { Certified, Visual }   // Certified เป็นค่าเริ่มต้น
public enum WordOutput { Pdf, Docx }              // Pdf เป็นค่าเริ่มต้น; ถูกละเว้นสำหรับแหล่ง PDF

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

เอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนได้, และส่วนขยายของมันพร้อมจุด ( ".pdf" หรือ ".docx" ).

SigningCertificate

csharp
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

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

หน้านี้เป็นประโยชน์หรือไม่?