پلاگین Signer

امضای اسناد PDF و Word با یک امضای قابل مشاهده و یک مهر دیجیتال

پلاگین Signer یک امضای قابل مشاهده بر روی سند می‌گذارد و به‌صورت پیش‌فرض، آن را با یک امضای دیجیتال مهر می‌زند که یک خواننده PDF می‌تواند آن را تأیید کند. این پلاگین فایل‌های PDF و Word (.docx) را امضا می‌کند. امضای قابل مشاهده همیشه یک تصویر PNG است: رسم‌شده، تایپ‌شده یا توسط امضاکننده بارگذاری شده.

سطحزمان استفاده
DocumentSigner (C#)شما روی سرور امضا می‌کنید، بدون درگیر شدن مرورگر
ویجت Drop‑in (doconutSigner.js)اگر می‌خواهید یک صفحه بارگذاری، امضا و دانلود آماده در صفحه خود داشته باشید
نقاط انتهایی HTTP بر روی 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 قرار دارد قرار می‌گیرد؛ همراه با مجوز ویور خوانده می‌شود.

ثبت پلاگین

مانند هر پلاگین 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 آن یک انتخاب جداگانه هستند، AddSignerWidget() (به ویجت Drop‑in نگاه کنید).

پلاگین به مجوزی نیاز دارد که قابلیت 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 خالی برمی‌گرداند و دلیل فقط در لاگ رویداد ویندوز (منبع ASP.NET) ثبت می‌شود. این استثنا برای عدم وجود مجوز، فایل قدیمی TRIAL، مجوز بدون Signer، و مجوز پرداخت‌شده‌ای که خارج از بازه نسخه آن استفاده شده است، رخ می‌دهد. مجوزهای موقت Demo/NFR پذیرفته می‌شوند. به راه‌اندازی مجوز مراجعه کنید.

مجوزدهی و واترمارک

وضعیت مجوزراه‌اندازیامضای معتبرامضای بصری
مجوز پرداخت‌شده که Signer را می‌دهد، گواهی‌نامه پیکربندی شدهشروع می‌کندمهر شده با گواهی‌نامه شما، تمیز (watermarked: false)تمیز
مجوز پرداخت‌شده که Signer را می‌دهد، بدون گواهی‌نامهشروع می‌کندرد شده: No signing certificate configured.تمیز
مجوز پرداخت‌شده، گواهی‌نامه منقضی شده یا هنوز معتبر نیستشروع می‌کندرد شده: The signing certificate expired on yyyy-MM-dd.تمیز
مجوز موقت Demo/NFR، فعال یا منقضی شدهشروع می‌کندمهر شده با گواهی‌نامه دموی داخلی، واترمارک شده (watermarked: true)واترمارک شده
بدون مجوز، فایل قدیمی TRIAL، مجوز بدون Signer، یا مجوز پرداخت‌شده خارج از بازه نسخهApplication_Start استثنا می‌اندازد؛ هر درخواست یک 500 خالی برمی‌گرداند——

قانون برای لایه C# و ویجت یکسان است: خروجی وقتی واترمارک می‌شود که مجوز یک مجوز پرداخت‌شده ویور نباشد یا موقت باشد. تحت یک مجوز موقت، پلاگین همیشه با گواهی‌نامه دموی داخلی امضا می‌کند و هر گواهی‌نامه‌ای که پیکربندی کنید استفاده نمی‌شود.

گواهی‌نامه دموی داخلی یک مهر واقعی تولید می‌کند، اما خوانندگان PDF به آن اعتماد ندارند. یک ادغام می‌تواند به‌صورت انتها به انتها بر روی یک مجوز ارزیابی ساخته و تست شود؛ برای دریافت خروجی تمیز و قابل اعتماد به هر دو مجوز پرداخت‌شده و گواهی‌نامه امضای خودتان نیاز دارید (گواهی‌نامه امضا).

استفاده از C#

DocumentSigner توسط DoconutHost.Initialize ثبت می‌شود؛ آن را از DoconutHost.Services حل کنید. سازنده آن داخلی است، بنابراین هرگز 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 را تحت یک لایسنس دموی، یا در حالت Visual پاس دهید.

SignResult سند امضا شده را به عنوان یک جریان قابل جستجو نگه می‌دارد، به‌همراه Extension آن (".pdf" یا ".docx") تا بتوانید فایل را نام‌گذاری کنید. شما مالک جریان هستید: هنگام اتمام آن را dispose کنید.

در یک کنترلر MVC 5

عملکرد را به صورت ناهمزمان کنید و await امضا را. این یکی یک امضای Visual می‌گذارد که نیازی به گواهی ندارد:

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 به جای بازگرداندن، هنگام عدم موفقیت فراخوانی استثنا می‌اندازد:

استثناپیامزمان
InvalidOperationExceptionNo signing certificate configured.حالت Certified، لایسنس پرداختی، و عدم ارسال گواهی
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.حالت Certified با گواهی خارج از بازه اعتبار
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 فقط قابل مقداردهی اولیه هستند، که C# 7.3 (پیش‌فرض برای پروژه‌های .NET Framework) نمی‌تواند تنظیم کند. <LangVersion> را به 9.0 یا نسخه‌ی بعدی در فایل پروژه تنظیم کنید.

گواهی فقط در حافظه نگهداری می‌شود. هرگز لاگ نمی‌شود، به مشتری بازگردانده نمی‌شود، یا ذخیره نمی‌شود، و رمز عبور هرگز در پیام خطا ظاهر نمی‌شود.

نیازمندی‌ها:

  • یک بسته PFX / PKCS#12 با کلید خصوصی آن. یک فایل فقط کلید عمومی (.cer, .crt) نمی‌تواند امضا کند. زنجیره صادرکننده را همراه آن صادر کنید تا مهرهای PDF بتوانند آن را حمل کنند.
  • رمز عبور صحیح.
  • درون بازه اعتبار آن. یک گواهی منقضی‌شده یا هنوز معتبر نیست، برنامه را متوقف نمی‌کند، اما امضاهای Certified تا جایگزین شدن رد می‌شوند. امضاهای Visual تحت تأثیر نیستند.
  • صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و یک استفاده کلید گسترش‌یافته، اگر موجود باشد، که اجازه امضای سند، حفاظت ایمیل یا احراز هویت مشتری را می‌دهد. گواهی صادر شده برای چیز دیگری، مانند گواهی سرور TLS، هنوز امضا می‌کند، اما خوانندگان PDF امضا را پرچم‌گذاری می‌کنند.
  • توکن‌های سخت‌افزاری، کارت‌های هوشمند، HSMها و فروشگاه گواهی ویندوز پشتیبانی نمی‌شوند. گواهی را همراه با کلید خصوصی و زنجیره‌اش به یک PFX صادر کنید.

یک PFX از گواهی و کلید خصوصی آن ایجاد کنید با OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# رمز عبور صادراتی که از شما درخواست می‌شود SigningCertificate.Password است.

از فروشگاه گواهی ویندوز یک مورد صادر کنید: certmgr.msc را باز کنید و گواهی را پیدا کنید (آیکون آن وقتی کلید خصوصی موجود باشد، یک کلید نشان می‌دهد). روی آن راست‑کلیک کنید، All Tasks → Export… را انتخاب کنید، Yes, export the private key را انتخاب کنید، Personal Information Exchange – PKCS #12 (.PFX) را برگزینید و یک رمز عبور تنظیم کنید.

بررسی‌های راه‌اندازی

هنگامی که ویجت فعال می‌شود، گواهی‌نامه در SignerWidgetOptions.SigningCertificate یک‌بار بررسی می‌شود، داخل DoconutHost.Initialize، بنابراین یک PFX پیکربندی نادرست در زمان راه‌اندازی شکست می‌خورد نه در اولین امضا. سه مشکل یک InvalidOperationException از Application_Start پرتاب می‌کنند، و هر درخواست سپس یک 500 خالی پاسخ می‌دهد؛ پیام در لاگ رویداد ویندوز است:

پیامراه‌حل
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

فعال‌سازی نقطه‌های انتهایی

نقطه‌های انتهایی ?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 نگاه کنید؛ برای امضای demo (آبی‌رنگ) آن را null بگذارید
    });
});
// System.Web کل بارگذاری را قبل از اینکه Doconut آن را ببیند می‌خواند: maxRequestLength (KB) و
// maxAllowedContentLength (bytes) در Web.config بالای MaxUploadMb ویجت.

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.

نقطه‌های انتهایی و اسکریپت توسط هندلر و ماژولی که در 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" />           <!-- کیلوبایت‌ها: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- بایت‌ها: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

یک بارگذاری که بدون Content-Length (تکه‌ای) ارسال شود و از محدودیت‌های میزبان فراتر رود نیز صفحهٔ خطای 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 برمی‌گرداند. مقدار پیش‌فرض basePath ویجت، /doconut، نقطه انتهای ASP.NET Core است؛ در این بسته باید '/DocImage.axd' باشد.

امضاکننده یک فایل PDF یا فایل .docx بارگذاری می‌کند، امضایی می‌سازد (Draw روی بوم، Type یک نام با فونت امضا، یا Image از یک PNG، JPG یا GIF)، آن را به صفحه می‌کشاند و اندازه‌اش را تغییر می‌دهد، سپس امضا می‌کند و نتیجه را دانلود می‌کند. ویجت همیشه امضا را به صورت PNG ارسال می‌کند؛ تصویر بارگذاری‌شده در مرورگر به PNG تبدیل می‌شود که به اندازه 520×160 می‌گنجد.

گزینه‌ها

گزینهنوعپیش‌فرضیادداشت‌ها
basePathstring'/doconut'جایی که نقاط انتهایی ?sign= و تصاویر پیش‌نمایش سرو می‌شوند. '/DocImage.axd' را در این بسته تنظیم کنید
resPathstring'/doconut-res'رزرو شده؛ ویجت CSS خود را بسته‌بندی می‌کند
maxUploadMbnumber25فقط بررسی سمت کلاینت، بنابراین فایل بزرگ‌تری به سرعت شکست می‌خورد. حداکثر سرور MaxUploadMb در AddSignerWidget است
maxSignatureKbnumber512حداکثر سمت کلاینت برای حالت Image. آن را برابر با MaxSignatureImageKb سرور نگه دارید
previewWidthnumber560عرض پیکسل پیش‌نمایش صفحه
licenseUrlstring | nullnullاعلان watermark دمو را به لینکی به این URL تبدیل می‌کند
signatureModestring'certified'نوع اولیه امضا: 'certified' یا 'visual'. هر مقدار دیگر به 'certified' تبدیل می‌شود
showSignatureModeTogglebooleantrueگزینه Digital signature / Visual only را نشان می‌دهد. با false، ویجت با signatureMode امضا می‌کند
wordOutputstring'pdf'خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل می‌شود
showOutputFormatTogglebooleantrueگزینه PDF / Word را نشان می‌دهد، فقط برای منابع .docx. با false، ویجت از 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 }

یک فراخوانی که خطا می‌اندازد، گرفته و ثبت می‌شود؛ هرگز جریان ویجت را خراب نمی‌کند.

دستگیره امری

متدرفتار
reset()به صفحهٔ رهاسازی برمی‌گردد و جریان جاری را پاک می‌کند. دوباره onReady را اجرا نمی‌کند. پس از destroy() هیچ کاری نمی‌کند
loadFile(file)جریان را با یک File شروع می‌کند. اگر ویجت در صفحهٔ رهاسازی نباشد کاری نمی‌کند؛ در صورت نیاز ابتدا reset() را فراخوانی کنید
destroy()لیسنرها را حذف می‌کند، mount را خالی می‌کند و نمونه را منجمد می‌سازد
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'.

کلیدپیش‌فرض انگلیسی
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 است. مسیرها تا زمانی که AddSignerWidget() فراخوانی شود به 404 پاسخ می‌دهند. خطاها شامل بدنه JSON هستند، { "error": "..." }، به جز مواردی که جدول می‌گوید «فقط وضعیت». مقدار ناشناخته‌ی ?sign= به 400 پاسخ می‌دهد.

مسیرهدفپاسخ موفقیت
POST /DocImage.axd?sign=open (چندبخشی، یک فایل)بارگذاری یک PDF یا .docx و باز کردن آن برای پیش‌نمایش200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (بدنه JSON)امضای فایل بارگذاری‌شده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"
}
فیلدیادداشت‌ها
tokenتوکن از open
signature.kindDrawn، Typed یا Image، بدون حساسیت به حروف؛ هر چیز دیگر به Drawn تبدیل می‌شود. فقط یک نکته: بارگذاری همیشه یک PNG است
signature.payloadیک PNG خالص base64، بدون پیشوند data:. باید یک PNG واقعی باشد و پس از رمزگشایی بزرگتر از MaxSignatureImageKb نباشد
placement.pageمبتنی بر ۱
placement.x / y / w / h0..1 نرمال‌شده از گوشه‌ی بالا-چپ، با x + w ≤ 1 و y + h ≤ 1
meta.signerName / reason / locationاختیاری. هر کدام برش می‌شوند، مقدار خالی حذف می‌شود، و هر کدام به ۲۵۶ کاراکتر کوتاه می‌شوند
wordOutputpdf (پیش‌فرض) یا docx؛ برای منابع PDF نادیده گرفته می‌شود. هر چیز دیگر به pdf تبدیل می‌شود
modecertified (پیش‌فرض) یا visual. هر چیز دیگر به certified تبدیل می‌شود

downloadName خروجی را دنبال می‌کند: <source>-signed.pdf یا <source>-signed.docx، و download Content-Type مطابقت را ارسال می‌کند.

منبع بارگذاری‌شده و نتیجه‌ی امضا شده هر کدام برای ۳۰ دقیقه نگهداری می‌شوند. پس از آن، run و download به 404 پاسخ می‌دهند و فایل باید دوباره باز شود. تمام توکن‌ها GUID هستند.

مسیروضعیتزمانبدنه
any404ویجت فعال نیستفقط وضعیت
any405فعل اشتباه (open و run به POST نیاز دارند، download به GET نیاز دارد)فقط وضعیت
open400بارگذاری چندبخشی نیستExpected 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توکن موجود نیست یا GUID نیستInvalid token.
run404بارگذاری منقضی شده یا هرگز باز نشده استUpload expired — please re-open the file.
run400امضا وجود ندارد یا قرارگیری نیستNo signature supplied. / No placement supplied.
run400بارگذاری base64 نیست، خالی است، خیلی بزرگ است یا PNG نیستSignature 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پردازش ناموفق بودپیام پاک‌سازی‌شده
download400توکن موجود نیست یا GUID نیستفقط وضعیت
download404توکن ناشناخته یا منقضی‌شدهفقط وضعیت

یک مسیر کامل با fetch:

javascript
// file: File برای امضا; pngBase64: امضا به صورت PNG base64 ساده، بدون پیشوند 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);
}

نقطه‌های انتهایی 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 را سرو کرده نگه می‌دارد. پشت یک بارگذاری‌کنندهٔ بار بدون نشست‌های چسبنده، یک درخواست بعدی 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;                   // حداقل ۳۲ بایت، یکسان در هر سرور
        // store.Ttl = TimeSpan.FromMinutes(30);   // چقدر یک بارگذاری نگهداری می‌شود (پیش‌فرض)
    }));
  • یک سرور تک‌نقشه به هیچ چیزی نیاز ندارد: بدون این فراخوانی، فروشگاه در‑حافظه استفاده می‌شود.
  • بارگذاری‌ها و نتایج در حالت استراحت بر روی اشتراک رمزگذاری می‌شوند (AES-256، encrypt-then-MAC)، و هر فایل به توکن خود متصل است، بنابراین یک توکن هرگز نمی‌تواند فایل توکن دیگر را بخواند.
  • FarmKey باید حداقل ۳۲ بایت باشد و در هر سرور یکسان باشد. آن را از یک مخزن راز بارگذاری کنید؛ هرگز به‌صورت ثابت کدنویسی نکنید. ثبت یک ArgumentException را زمانی که RootPath موجود نیست یا FarmKey کوتاه‌تر از ۳۲ بایت باشد، پرتاب می‌کند.
  • RootPath را به همان مکان مشترکی که نمایشگر توزیع‌شده استفاده می‌کند اشاره دهید، و به هر سرور همان گواهی امضای مشترک را بدهید.

مرجع API

Facade و گزینه‌های ویجت در فضای نام 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 حل می‌شود؛ سازنده داخلی است. 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 and 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 بر پایهٔ ۱ است؛ X، Y، W و H از گوشهٔ بالا‑چپ به صورت 0..1 نرمال‌سازی می‌شوند.

SignatureMode and 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 خالی نیست
}

یا PfxBytes یا PfxPath را تنظیم کنید، به‌علاوه Password. تنظیم‌کننده‌ها فقط init هستند: پروژه به 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 را برمی‌گرداند تا فراخوانی‌ها زنجیره‌ای شوند. یک 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 به فایلی که وجود ندارد اشاره می‌کندمسیر را اصلاح کنید؛ فایل را در جایی مستقر کنید که حساب استخر برنامه بتواند آن را بخواند
لاگ رویداد نشان می‌دهد 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 را تنظیم کند<LangVersion> را به 9.0 یا بالاتر تنظیم کنید
حل کردن DocumentSigner استثنای No IDocumentSigner is registered. را پرتاب می‌کندSignerPlugin ثبت نشده استAddPlugin<SignerPlugin>() را در DoconutHost.Initialize اضافه کنید
خروجی دارای واترمارک استمجوز موقت است (دمو/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.پنجرهٔ ۳۰‑دقیقه‌ای سپری شده است، یا سرور دیگری در فارم بارگذاری را نداردفایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید
یک .docx امضا شده در برخی نمایشگرها امضا نشان نمی‌دهدخروجی Word شامل امضای بستهٔ OOXML است که بسیاری از نمایشگرها نشان نمی‌دهندبه PDF امضا کنید، که پیش‌فرض است
خوانندگان PDF می‌گویند هویت امضاکننده ناشناخته استخواننده ریشهٔ گواهی را اعتماد نمی‌کند (گواهی دموی هرگز مورد اعتماد نیست)از گواهی‌ای از ریشه‌ای که خوانندگان شما به آن اعتماد دارند استفاده کنید
ویجت وقتی UI در منبع دیگری است شکست می‌خوردنقطه‌های انتهایی پشتیبانی CORS ندارندUI را از همان منبع سرو کنید، یا DocImage.axd و /doconut-res را به‌صورت reverse‑proxy کنید
قالب اعمال نمی‌شودانتخابگر به عنصری داخل mount هدف می‌گیردمستقیم به mount هدف بگیرید: #host.dsw یا #host

یادداشت‌های چارچوب

در مقایسه با بسته‌های ASP.NET Core، این بسته فقط در میزبانی متفاوت است؛ API، قرارداد نقطه انتهایی، اسکریپت ویجت و قوانین مجوزدهی یکسان هستند.

  • ثبت‌نام در Application_Start قرار دارد، از طریق DoconutHost.Initialize، به جای builder.Services.AddDoconut. سرویس‌هایی مانند AddDoconutDistributedWidgets در آرگومان دوم آن قرار می‌گیرند.
  • نقطه‌های انتهایی توسط DocImage.axd سرویس می‌شوند و اسکریپت توسط DoconutResourceModule، هر دو در Web.config ثبت شده‌اند، به جای UseDoconut() و UseDoconutResources(). ویجت به basePath: '/DocImage.axd' نیاز دارد.
  • خطاهای راه‌اندازی به‌صورت یک 500 خالی در هر درخواست ظاهر می‌شوند، با دلیل در لاگ رویدادهای ویندوز.
  • بارگذاری‌ها به‌صورت کامل توسط ASP.NET خوانده می‌شوند قبل از اینکه Doconut آنها را ببیند، بنابراین محدودیت‌های IIS باید بالاتر از MaxUploadMb باشند.
  • بدون خط لاگ راه‌اندازی درباره گواهی‌نامه: سه خطای گواهی‌نامه همچنان پرتاب می‌شوند، اما خطی که نام گواهی‌نامه را می‌نویسد نوشته نمی‌شود.
  • C# 9.0 یا بعدی برای تنظیم ویژگی‌های فقط‑مقداری SigningCertificate لازم است.
  • فقط ویندوز، مانند بقیه بسته .NET Framework.

آیا این صفحه مفید بود؟