ملحق Signer
توقيع مستندات PDF و Word بتوقيع مرئي وختم رقمي
يضع ملحق Signer توقيعًا مرئيًا على المستند، وبشكل افتراضي، يختمه بتوقيع رقمي يمكن لقارئ PDF التحقق منه. يقوم بتوقيع ملفات PDF و Word (.docx). يكون التوقيع المرئي دائمًا صورة PNG: مرسومة، مكتوبة، أو تم تحميلها من قبل الموقّع.
| السطح | متى تستخدمه |
|---|---|
DocumentSigner (C#) | توقيع على الخادم، دون مشاركة المتصفح |
Drop-in widget (doconutSigner.js) | تريد شاشة تحميل، توقيع وتنزيل جاهزة في صفحتك |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | تبني واجهة مستخدم توقيع خاصة بك مقابل عقد خادم موثّق |
يتم وضع كل توقيع مرة واحدة، على صفحة واحدة. يمكن أن يحمل اسم الموقّع والسبب والموقع معه.
تثبيت الحزمة
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() (انظر القطعة المدمجة).
يحتاج الملحق إلى ترخيص يمنح القدرة على Signer. بدون ذلك، يطلق DoconutHost.Initialize استثناءً من Application_Start:
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.في System.Web يعني ذلك أن كل طلب يرد بـ 500 فارغ، والسبب يكون فقط في سجل أحداث Windows (المصدر 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");
// الوضع الافتراضي هو 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") لتتمكن من تسمية الملف. أنت مالك التيار: حرّره عندما تنتهي.
في وحدة تحكم 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 هي init‑only، وهو ما لا يمكن لـ C# 7.3 (الافتراضي لمشاريع .NET Framework) تعيينه. اضبط <LangVersion> إلى 9.0 أو أحدث في ملف المشروع.
تُحفظ الشهادة في الذاكرة فقط. لا تُسجل أبدًا، ولا تُعاد إلى العميل، ولا تُحفظ، ولا تظهر كلمة المرور أبدًا في رسالة خطأ.
المتطلبات:
- حزمة PFX / PKCS#12 مع المفتاح الخاص. ملف يحتوي على المفتاح العام فقط (
.cer,.crt) لا يمكنه التوقيع. صدّر سلسلة المصدر معه، حتى تتمكن أختام PDF من حملها. - كلمة المرور الصحيحة.
- داخل فترة الصلاحية الخاصة به. شهادة منتهية الصلاحية أو غير صالحة بعد لا توقف التطبيق، لكن التوقيعات Certified تُرفض حتى يتم استبدالها. التوقيعات Visual لا تتأثر.
- مصدرة لتوقيع المستندات: استخدام المفتاح مع التوقيع الرقمي أو عدم الإنكار، واستخدام مفتاح ممتد، إذا كان موجودًا، يسمح بتوقيع المستندات، أو حماية البريد الإلكتروني أو مصادقة العميل. شهادة صادرة لشيء آخر، مثل شهادة خادم TLS، لا تزال توقع، لكن قارئات PDF تُعلم عن التوقيع.
- الرموز المادية، البطاقات الذكية، HSMs ومتجر شهادات Windows غير مدعومة. صدّر الشهادة، مع مفتاحها الخاص وسلسلتها، إلى PFX.
إنشاء PFX من شهادة ومفتاحها الخاص باستخدام OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# كلمة مرور التصدير التي يُطلب منك إدخالها هي SigningCertificate.Password.صدّر واحدة من متجر شهادات Windows: افتح certmgr.msc وابحث عن الشهادة (أيقونتها تظهر مفتاحًا عندما يكون المفتاح الخاص موجودًا). انقر بزر الماوس الأيمن عليها، اختر All Tasks → Export…، حدد Yes, export the private key، اختر Personal Information Exchange – PKCS #12 (.PFX)، وضع كلمة مرور.
فحوصات بدء التشغيل
عند تمكين الودجت، يتم فحص الشهادة في SignerWidgetOptions.SigningCertificate مرة واحدة، داخل DoconutHost.Initialize، لذا فإن ملف PFX غير المُكوَّن بشكل صحيح يفشل عند بدء التشغيل بدلاً من الفشل عند التوقيع الأول. ثلاث مشكلات تُطلق 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 تُقرأ عند التوقيع، لذا فإن المسار أو كلمة المرور الخاطئة تُفشل ذلك الاستدعاء.
عنصر واجهة المستخدم القابل للإدماج
تمكين نقاط النهاية
نقاط النهاية ?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: انظر إعداد الشهادة؛ اتركه null لتوقيع العرض التجريبي (مع علامة مائية)
});
});
// System.Web يقرأ كامل التحميل قبل أن يراه Doconut: احتفظ بـ maxRequestLength (KB) و
// maxAllowedContentLength (bytes) في Web.config فوق MaxUploadMb الخاص بالـ widget.AddSignerWidget() مع عدم تمرير أي وسيط يُفعِّل الودجت بالإعدادات الافتراضية. لا يمنح التوقيع بحد ذاته: يحتاج إلى AddPlugin<SignerPlugin>()، أو يطرح DoconutHost.Initialize:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.نقاط النهاية والسكريبت تُقدَّم بواسطة المعالج والوحدة المسجلة في Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>الوحدة تُقدِّم السكريبت سواء كان الودجت مفعَّلًا أم لا. بدون AddSignerWidget()، يُحمَّل الودجت ويرسم منطقة الإسقاط الخاصة به، وأول طلب له يرد بـ 404؛ ثم يُبلغ الودجت عن Signing is not enabled on this server..
حدود التحميل
يقوم ASP.NET بقراءة كامل جسم الطلب قبل تشغيل DocImage.axd. تحميل يتجاوز MaxUploadMb لكن أقل من حدود المضيف يحصل على JSON الخاص بالودجت 413 (File is too large.). تحميل يتجاوز حدود المضيف يُرفض أولًا بواسطة IIS، مع صفحة خطأ لا يستطيع الودجت قراءتها. حافظ على أن تكون حدود المضيف أعلى من حد الودجت:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>التحميل المرسل بدون Content-Length (مجزأ) والذي يتجاوز حدود المضيف يحصل أيضًا على صفحة خطأ 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 أو عنصرًا، يطرح استثناءً إذا لم يتم العثور على التركيب، ويعيد مقبضًا. القيمة الافتراضية للـ widget basePath، /doconut، هي نقطة النهاية ASP.NET Core؛ في هذه الحزمة يجب أن تكون '/DocImage.axd'.
يقوم المُوقّع بتحميل ملف PDF أو ملف .docx، يُنشئ توقيعًا (Draw على لوحة رسم، Type اسمًا بخط توقيع، أو Image من PNG أو JPG أو GIF)، يسحبها ويُعيد تحجيمها على الصفحة، ثم يوقع ويُحمّل النتيجة. يُرسل الـ widget دائمًا التوقيع كملف PNG؛ تُحوَّل الصورة التي تم تحميلها في المتصفح إلى PNG يتناسب مع 520×160.
الخيارات
| الخيار | النوع | الافتراضي | ملاحظات |
|---|---|---|---|
basePath | string | '/doconut' | أين يتم تقديم نقاط النهاية ?sign= وصور المعاينة. اضبط '/DocImage.axd' في هذه الحزمة |
resPath | string | '/doconut-res' | محجوز؛ الـ widget يتضمن CSS الخاص به |
maxUploadMb | number | 25 | فحص من جانب العميل فقط، لذا فإن الملف الضخم يفشل بسرعة. الحد الأقصى على الخادم هو MaxUploadMb في AddSignerWidget |
maxSignatureKb | number | 512 | الحد الأقصى من جانب العميل لوضع الصورة. اجعله مساويًا لـ MaxSignatureImageKb على الخادم |
previewWidth | number | 560 | عرض البكسل لمعاينة الصفحة |
licenseUrl | string | null | null | يحوّل إشعار العلامة المائية التجريبية إلى رابط لهذا العنوان |
signatureMode | string | 'certified' | نوع التوقيع الأولي: 'certified' أو 'visual'. أي قيمة أخرى تصبح 'certified' |
showSignatureModeToggle | boolean | true | يعرض خيار Digital signature / Visual only. مع false، يوقع الـ widget باستخدام signatureMode |
wordOutput | string | 'pdf' | الإخراج الأولي لمصادر .docx: 'pdf' أو 'docx'. أي قيمة أخرى تصبح 'pdf' |
showOutputFormatToggle | boolean | true | يعرض خيار PDF / Word، لمصادر .docx فقط. مع false، يستخدم الـ widget wordOutput |
labels | object | {} | يتجاوز أي مجموعة فرعية من السلاسل الإنجليزية |
إخفاء زر التبديل لا يعطل الميزة؛ بل يثبت القيمة. إعدادان شائعان:
// يظهر كلا المفتاحين، التوقيع الرقمي بشكل افتراضي: موقع كامل ذاتي الخدمة.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// مرئي فقط، بدون مفتاح: طابع بسيط دون تقديم توقيع رقمي.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});ردود النداء
| النداء | يُطلق عندما | الحمولة |
|---|---|---|
onReady | مرة واحدة عند التركيب (ليس مرة أخرى على reset()) | — |
onSourceLoaded | يتم فتح الملف وعرض معاينته | { file: { token, name, pages, ext } } |
onSigned | نجاح التوقيع | { downloadToken, downloadName, watermarked } |
onDownload | عند كل نقرة على تحميل | { downloadName, downloadToken } |
onError | فشل خطوة الفتح أو التوقيع أو التحميل، أو أن ملف وضع الصورة كبير جدًا | { message } |
يتم التقاط أي نداء يرمي استثناءً وتسجيله؛ لا يعرقل تدفق الـ widget أبدًا.
مقبض إجرائي
| الطريقة | السلوك |
|---|---|
reset() | يعيد إلى شاشة الإسقاط ويمسح التدفق الحالي. لا يُطلق onReady مرة أخرى. لا فعل بعد destroy() |
loadFile(file) | يبدأ التدفق بـ File. لا فعل إلا إذا كان الـ widget على شاشة الإسقاط؛ استدعِ reset() أولاً إذا لزم الأمر |
destroy() | يزيل المستمعين، يفرغ التركيب، ويجمد النسخة |
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، خط واجهة نظام، وخط توقيع مائل.
أنشئ الواجهة الأمامية الخاصة بك
الودجت هو عميل لهذا العقد HTTP على DocImage.axd. المسارات ترد بـ 404 حتى يتم استدعاء AddSignerWidget(). الأخطاء تحمل جسم JSON، { "error": "..." }، باستثناء حيث تقول الجدول "الحالة فقط". قيمة غير معروفة لـ ?sign= ترد بـ 400.
| المسار | الغرض | استجابة النجاح |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | رفع ملف PDF أو .docx وفتحها للمعاينة | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | توقيع الملف المرفوع | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | بث الملف الموقع | 200 — الملف، Content-Disposition: attachment، Cache-Control: no-store |
ext في استجابة open يتضمن النقطة الرائدة (".docx"). معاينة الصفحة تستخدم مسار صورة العارض القياسي، /DocImage.axd?token={token}&page={n}&thumb=1&width={px}؛ الصفحة المعروضة تصبح placement.page.
جسم run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| الحقل | ملاحظات |
|---|---|
token | الرمز من open |
signature.kind | Drawn، Typed أو Image، غير حسّاس لحالة الأحرف؛ أي شيء آخر يصبح Drawn. تلميح فقط: الحمولة دائمًا PNG |
signature.payload | صورة PNG مشفّرة base64 فقط، بدون بادئة data:. يجب أن تكون PNG حقيقية ولا يزيد حجمها عن MaxSignatureImageKb بعد فك الترميز |
placement.page | مبني على 1 |
placement.x / y / w / h | 0..1 مُعَدّل من الزاوية العليا اليسرى، مع x + w ≤ 1 و y + h ≤ 1 |
meta.signerName / reason / location | اختياري. كل واحد يُقَصّ، تُحذف القيم الفارغة، ويُقَصّ كل واحد إلى 256 حرفًا |
wordOutput | pdf (الافتراضي) أو docx؛ يُهمل لمصادر PDF. أي شيء آخر يصبح pdf |
mode | certified (الافتراضي) أو visual. أي شيء آخر يصبح certified |
downloadName يتبع المخرجات: <source>-signed.pdf أو <source>-signed.docx، وdownload يرسل Content-Type المطابق.
المصدر المرفوع والنتيجة الموقعة يُحتفظ بهما كلٌ لمدة 30 دقيقة. بعد ذلك، run وdownload يردان بـ 404 ويجب فتح الملف مرة أخرى. جميع الرموز هي GUIDs.
| المسار | الحالة | متى | المحتوى |
|---|---|---|---|
| أي | 404 | الودجت غير مفعّل | الحالة فقط |
| أي | 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: الملف لتوقيعه; 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);
}النقاط النهاية هي نفس الأصل: هذا الإصدار لا يدعم CORS. قدّم واجهة المستخدم الخاصة بك وسكريبت الودجت من نفس الأصل الذي يعمل عليه التطبيق، أو استخدم reverse-proxy DocImage.axd و /doconut-res تحت أصل واجهة المستخدم الخاصة بك.
في الإنتاج
-
قم بتثبيت الإضافة بجوار حزمة النواة، بنفس الإصدار:
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) تُصدر، حسب علمنا، باستخدام المفتاح الخاص على رمز مادي أو 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; // على الأقل 32 بايت، متطابق على كل خادم
// store.Ttl = TimeSpan.FromMinutes(30); // المدة التي يُحتفظ فيها بالتحميل (الإعداد الافتراضي)
}));- لا يحتاج خادم واحد إلى أي شيء: بدون هذا الاستدعاء يُستخدم المخزن في الذاكرة.
- يتم تشفير عمليات التحميل والنتائج أثناء التخزين على المشاركة (AES-256، تشفير ثم MAC)، ويُربط كل ملف برمز التوكن الخاص به، لذا لا يمكن لتوكن واحد قراءة ملف توكن آخر.
- يجب أن يكون
FarmKeyبطول لا يقل عن 32 بايت وأن يكون نفسه على كل خادم. حمّله من مخزن أسرار؛ لا تقم بتضمينه صراحةً. يُطلق التسجيل استثناءًArgumentExceptionعندما يكونRootPathمفقودًا أو يكونFarmKeyأقصر من 32 بايت. - وجه
RootPathإلى نفس الموقع المشترك الذي يستخدمه المشاهد الموزع، وامنح كل خادم نفس شهادة التوقيع.
مرجع API
الواجهة وخيارات الودجت موجودة في مساحة الاسم 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 و SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes ليس فارغًا
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes هو PNG لكل نوع. التوقيع المرسوم أو المكتوب يكون شفافًا؛ الصورة التي تم تحميلها تحتفظ بالشفافية التي كانت عليها، لذا يبقى JPG غير شفاف كما هو. Kind هو مجرد تلميح.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page يبدأ من 1؛ X، Y، W وH هي 0..1 مُطَبَّقة من الزاوية العليا اليسرى.
SignatureMode و WordOutput
public enum SignatureMode { Certified, Visual } // Certified هو الافتراضي
public enum WordOutput { Pdf, Docx } // Pdf هو الافتراضي; يتم تجاهله لمصادر PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);المستند الموقّع كدفق قابل للتمرير، وامتداده مع النقطة (".pdf" أو ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes ليس فارغًا، أو PfxPath ليس فارغًا
}عيّن إما PfxBytes أو PfxPath، بالإضافة إلى Password. المُعدِّلات هي init‑only: المشروع يحتاج إلى C# 9.0 أو أحدث.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}يُعيّن عبر DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null)، الذي يُعيد DoconutOptions بحيث يمكن ربط الاستدعاءات. قيمة null في SigningCertificate تعني شهادة العرض التجريبية تحت رخصة مؤقتة، وتكون التوقيعات البصرية فقط تحت رخصة مدفوعة.
استكشاف الأخطاء وإصلاحها
| العَرَض | السبب | الحل |
|---|---|---|
كل طلب يُعيد 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‑only | عيّن <LangVersion> إلى 9.0 أو أحدث |
حل DocumentSigner يثير No IDocumentSigner is registered. | SignerPlugin غير مسجل | أضف AddPlugin<SignerPlugin>() في DoconutHost.Initialize |
| الناتج مائي | الرخصة مؤقتة (Demo/NFR) | استخدم رخصة مدفوعة تمنح Signer |
run يجيب 400 No signing certificate configured. | رخصة مدفوعة، وضع Certified، ولا شهادة | اضبط SigningCertificate، أو وقع في الوضع البصري |
run يجيب 400 The signing certificate expired on yyyy-MM-dd. | الشهادة منتهية الصلاحية | استبدلها؛ التوقيعات البصرية تستمر في العمل في هذه الأثناء |
الودجت يُحمَّل لكنه يقول 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. | واجهة مخصصة أرسلت عنوان 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 تقول إن هوية الموقّع غير معروفة | القارئ لا يثق بجذر الشهادة (شهادة العرض التجريبية لا تُوثق أبدًا) | استخدم شهادة من جذر يثق به قارئوك |
| الودجت يفشل عندما تكون الواجهة على أصل مختلف | النقاط النهاية لا تدعم CORS | قدّم الواجهة من نفس الأصل، أو استخدم reverse‑proxy لـ DocImage.axd و/doconut-res |
| السمة لا تُطبق | المحدد يستهدف عنصرًا داخل الـ 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فارغ في كل طلب، مع السبب في سجل أحداث Windows. - التحميلات تُقرأ بالكامل بواسطة ASP.NET قبل أن يراها Doconut، لذا يجب أن تكون حدود IIS أعلى من
MaxUploadMb. - لا سطر سجل بدء حول الشهادة: لا تزال الأخطاء الثلاثة المتعلقة بالشهادة تُرمى، لكن السطر الذي يذكر الشهادة غير مكتوب.
- C# 9.0 أو أحدث مطلوب لتعيين خصائص init-only الخاصة بـ
SigningCertificate. - Windows فقط، مثل باقي حزمة .NET Framework.
هل كانت هذه الصفحة مفيدة؟