پلاگین Signer
امضای اسناد PDF و Word با یک امضای قابل مشاهده و یک مهر دیجیتال
پلاگین Signer یک امضای قابل مشاهده بر روی سند میگذارد و بهصورت پیشفرض، آن را با یک امضای دیجیتال مهر میزند که یک خواننده PDF میتواند آن را تأیید کند. این پلاگین فایلهای PDF و Word (.docx) را امضا میکند. امضای قابل مشاهده همیشه یک تصویر PNG است: رسمشده، تایپشده یا توسط امضاکننده بارگذاری شده.
| سطح | زمان استفاده |
|---|---|
DocumentSigner (C#) | شما روی سرور امضا میکنید، بدون درگیر شدن مرورگر |
ویجت Drop‑in (doconutSigner.js) | اگر میخواهید یک صفحه بارگذاری، امضا و دانلود آماده در صفحه خود داشته باشید |
نقاط انتهایی HTTP بر روی 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 قرار دارد قرار میگیرد؛ همراه با مجوز ویور خوانده میشود.
ثبت پلاگین
مانند هر پلاگین 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 آن یک انتخاب جداگانه هستند، AddSignerWidget() (به ویجت Drop‑in نگاه کنید).
پلاگین به مجوزی نیاز دارد که قابلیت 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 خالی برمیگرداند و دلیل فقط در لاگ رویداد ویندوز (منبع 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>(). میشود.
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 میگذارد که نیازی به گواهی ندارد:
[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 به جای بازگرداندن، هنگام عدم موفقیت فراخوانی استثنا میاندازد:
| استثنا | پیام | زمان |
|---|---|---|
InvalidOperationException | No signing certificate configured. | حالت Certified، لایسنس پرداختی، و عدم ارسال گواهی |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | حالت Certified با گواهی خارج از بازه اعتبار |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | بایتهای PNG خالی، یا قرارگیری نامعتبر |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | هر نوع منبع دیگر |
حالتهای امضا، خروجی Word و گواهیها
حالتهای امضا
SignRequest.Mode انتخاب میکند که آیا امضا مهر میشود یا نه.
| حالت | چه چیزی تولید میکند | گواهی | قابل تأیید |
|---|---|---|---|
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 فقط قابل مقداردهی اولیه هستند، که C# 7.3 (پیشفرض برای پروژههای .NET Framework) نمیتواند تنظیم کند. <LangVersion> را به 9.0 یا نسخهی بعدی در فایل پروژه تنظیم کنید.
گواهی فقط در حافظه نگهداری میشود. هرگز لاگ نمیشود، به مشتری بازگردانده نمیشود، یا ذخیره نمیشود، و رمز عبور هرگز در پیام خطا ظاهر نمیشود.
نیازمندیها:
- یک بسته PFX / PKCS#12 با کلید خصوصی آن. یک فایل فقط کلید عمومی (
.cer,.crt) نمیتواند امضا کند. زنجیره صادرکننده را همراه آن صادر کنید تا مهرهای PDF بتوانند آن را حمل کنند. - رمز عبور صحیح.
- درون بازه اعتبار آن. یک گواهی منقضیشده یا هنوز معتبر نیست، برنامه را متوقف نمیکند، اما امضاهای Certified تا جایگزین شدن رد میشوند. امضاهای Visual تحت تأثیر نیستند.
- صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و یک استفاده کلید گسترشیافته، اگر موجود باشد، که اجازه امضای سند، حفاظت ایمیل یا احراز هویت مشتری را میدهد. گواهی صادر شده برای چیز دیگری، مانند گواهی سرور TLS، هنوز امضا میکند، اما خوانندگان PDF امضا را پرچمگذاری میکنند.
- توکنهای سختافزاری، کارتهای هوشمند، HSMها و فروشگاه گواهی ویندوز پشتیبانی نمیشوند. گواهی را همراه با کلید خصوصی و زنجیرهاش به یک PFX صادر کنید.
یک PFX از گواهی و کلید خصوصی آن ایجاد کنید با OpenSSL:
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 سرو میشوند و بهصورت پیشفرض غیرفعال هستند. آنها را در کنار ثبت افزونه فعال کنید:
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 پرتاب میکند:
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 ثبت شدهاند سرو میشوند:
<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" /> <!-- کیلوبایتها: 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 را به هندلر اشاره کنید:
<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 میگنجد.
گزینهها
| گزینه | نوع | پیشفرض | یادداشتها |
|---|---|---|---|
basePath | string | '/doconut' | جایی که نقاط انتهایی ?sign= و تصاویر پیشنمایش سرو میشوند. '/DocImage.axd' را در این بسته تنظیم کنید |
resPath | string | '/doconut-res' | رزرو شده؛ ویجت CSS خود را بستهبندی میکند |
maxUploadMb | number | 25 | فقط بررسی سمت کلاینت، بنابراین فایل بزرگتری به سرعت شکست میخورد. حداکثر سرور MaxUploadMb در AddSignerWidget است |
maxSignatureKb | number | 512 | حداکثر سمت کلاینت برای حالت Image. آن را برابر با MaxSignatureImageKb سرور نگه دارید |
previewWidth | number | 560 | عرض پیکسل پیشنمایش صفحه |
licenseUrl | string | null | null | اعلان watermark دمو را به لینکی به این URL تبدیل میکند |
signatureMode | string | 'certified' | نوع اولیه امضا: 'certified' یا 'visual'. هر مقدار دیگر به 'certified' تبدیل میشود |
showSignatureModeToggle | boolean | true | گزینه Digital signature / Visual only را نشان میدهد. با false، ویجت با signatureMode امضا میکند |
wordOutput | string | 'pdf' | خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل میشود |
showOutputFormatToggle | boolean | true | گزینه PDF / Word را نشان میدهد، فقط برای منابع .docx. با false، ویجت از 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 } |
یک فراخوانی که خطا میاندازد، گرفته و ثبت میشود؛ هرگز جریان ویجت را خراب نمیکند.
دستگیره امری
| متد | رفتار |
|---|---|
reset() | به صفحهٔ رهاسازی برمیگردد و جریان جاری را پاک میکند. دوباره onReady را اجرا نمیکند. پس از destroy() هیچ کاری نمیکند |
loadFile(file) | جریان را با یک File شروع میکند. اگر ویجت در صفحهٔ رهاسازی نباشد کاری نمیکند؛ در صورت نیاز ابتدا reset() را فراخوانی کنید |
destroy() | لیسنرها را حذف میکند، mount را خالی میکند و نمونه را منجمد میسازد |
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'.
| کلید | پیشفرض انگلیسی |
|---|---|
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 است. مسیرها تا زمانی که 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:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| فیلد | یادداشتها |
|---|---|
token | توکن از open |
signature.kind | Drawn، Typed یا Image، بدون حساسیت به حروف؛ هر چیز دیگر به Drawn تبدیل میشود. فقط یک نکته: بارگذاری همیشه یک PNG است |
signature.payload | یک PNG خالص base64، بدون پیشوند data:. باید یک PNG واقعی باشد و پس از رمزگشایی بزرگتر از MaxSignatureImageKb نباشد |
placement.page | مبتنی بر ۱ |
placement.x / y / w / h | 0..1 نرمالشده از گوشهی بالا-چپ، با x + w ≤ 1 و y + h ≤ 1 |
meta.signerName / reason / location | اختیاری. هر کدام برش میشوند، مقدار خالی حذف میشود، و هر کدام به ۲۵۶ کاراکتر کوتاه میشوند |
wordOutput | pdf (پیشفرض) یا docx؛ برای منابع PDF نادیده گرفته میشود. هر چیز دیگر به pdf تبدیل میشود |
mode | certified (پیشفرض) یا visual. هر چیز دیگر به certified تبدیل میشود |
downloadName خروجی را دنبال میکند: <source>-signed.pdf یا <source>-signed.docx، و download Content-Type مطابقت را ارسال میکند.
منبع بارگذاریشده و نتیجهی امضا شده هر کدام برای ۳۰ دقیقه نگهداری میشوند. پس از آن، run و download به 404 پاسخ میدهند و فایل باید دوباره باز شود. تمام توکنها GUID هستند.
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| any | 404 | ویجت فعال نیست | فقط وضعیت |
| any | 405 | فعل اشتباه (open و run به POST نیاز دارند، download به GET نیاز دارد) | فقط وضعیت |
open | 400 | بارگذاری چندبخشی نیست | 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 | بارگذاری 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 | پردازش ناموفق بود | پیام پاکسازیشده |
download | 400 | توکن موجود نیست یا GUID نیست | فقط وضعیت |
download | 404 | توکن ناشناخته یا منقضیشده | فقط وضعیت |
یک مسیر کامل با fetch:
// 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 خود.
در محیط تولید
-
پلاگین را نصب کنید در کنار بستهٔ هسته، با همان نسخه:
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 را سرو کرده نگه میدارد. پشت یک بارگذاریکنندهٔ بار بدون نشستهای چسبنده، یک درخواست بعدی 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; // حداقل ۳۲ بایت، یکسان در هر سرور
// 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
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
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}یک امضای قابل مشاهده یک بار قرار میگیرد، بهاضافهٔ فرادادهٔ اختیاری امضاکننده.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes خالی نیست
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes یک PNG برای هر نوع است. یک امضای کشیدهشده یا تایپشده شفاف است؛ تصویری که بارگذاری میشود شفافیت خود را حفظ میکند، بنابراین یک JPG مات همانطور که هست باقی میماند. Kind فقط یک نکته است.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H < 1
}Page بر پایهٔ ۱ است؛ X، Y، W و H از گوشهٔ بالا‑چپ به صورت 0..1 نرمالسازی میشوند.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified پیشفرض است
public enum WordOutput { Pdf, Docx } // Pdf پیشفرض است; برای منابع PDF نادیده گرفته میشودSignResult
public sealed record SignResult(Stream Stream, string Extension);سند امضا شده بهصورت یک جریان قابل جستجو، و پسوند آن با نقطه (".pdf" یا ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes خالی نیست، یا PfxPath خالی نیست
}یا PfxBytes یا PfxPath را تنظیم کنید، بهعلاوه Password. تنظیمکنندهها فقط init هستند: پروژه به 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 را برمیگرداند تا فراخوانیها زنجیرهای شوند. یک 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.
آیا این صفحه مفید بود؟