İmzalayıcı Eklentisi
PDF ve Word belgelerini görünür bir imza ve dijital mühürle imzalayın
Signer eklentisi bir belgeye görünür bir imza ekler ve varsayılan olarak, bir PDF okuyucusunun doğrulayabileceği dijital bir imza ile mühürler. PDF ve Word (.docx) dosyalarını imzalar. Görünür imza her zaman bir PNG görüntüsüdür: imzalayan tarafından çizilmiş, yazılmış veya yüklenmiş.
| Yüzey | Ne zaman kullanılır |
|---|---|
DocumentSigner (C#) | Sunucuda imzalıyorsunuz, tarayıcı kullanılmaz |
Drop-in widget (doconutSigner.js) | Sayfanızda hazır bir yükleme, imzalama ve indirme ekranı istiyorsunuz |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Belgelendirilmiş bir sunucu sözleşmesine karşı kendi imzalama UI'nizi oluşturuyorsunuz |
Her imza bir kez, tek bir sayfaya yerleştirilir. İmzalayanın adı, nedeni ve konumu onunla birlikte taşınabilir.
Paketi kurun
Install-Package Doconut.NETFramework.SignerBu belgenin açıkladığı sürüme eklentiyi sabitlemek için:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Signer paketini Doconut.NETFramework ile aynı sürümde tutun.
Eklentinin lisans dosyası Doconut.Viewer.Signer.lic, Doconut.Viewer.lic ile aynı klasöre konur; görüntüleyici lisansı ile birlikte okunur.
Eklentiyi kaydedin
Her Doconut eklentisi gibi, Signer AddPlugin<TPlugin>() ile DoconutHost.Initialize içinde kaydolur, Application_Start'den çağrılır:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Doconut.DoconutHost.Shutdown()'yi Application_End'ye ekleyin, böylece uygulama havuzu yeniden başlatıldığında arka plan işi düzgün durur.
Bu, C# arayüzünün ihtiyaç duyduğu her şeydir. Widget ve HTTP uç noktaları ayrı bir opt‑in'dir, AddSignerWidget() (bkz. Drop-in widget).
Eklenti, Signer yeteneğini veren bir lisansa ihtiyaç duyar. Lisans olmadan, DoconutHost.Initialize Application_Start'den bir hata fırlatır:
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 içinde bu, her isteğin boş bir 500 ile yanıt verdiği anlamına gelir ve neden yalnızca Windows olay günlüğünde (kaynak ASP.NET) bulunur. Lisans yoksa, eski bir TRIAL dosyası, Signer içermeyen bir lisans ve sürüm penceresinin dışındaki bir ücretli lisans için hata fırlatır. Geçici Demo/NFR lisansları kabul edilir. Bakınız License Setup.
Lisanslama ve filigran
| Lisans durumu | Başlangıç | Sertifikalı imza | Görsel imza |
|---|---|---|---|
Ücretli lisans Signer verir, sertifika yapılandırıldı | Başlar | Sertifikanızla mühürlenir, temiz (watermarked: false) | Temiz |
Ücretli lisans Signer verir, sertifika yok | Başlar | Reddedildi: No signing certificate configured. | Temiz |
| Ücretli lisans, sertifika süresi dolmuş veya henüz geçerli değil | Başlar | Reddedildi: The signing certificate expired on yyyy-MM-dd. | Temiz |
| Geçici Demo/NFR lisansı, aktif veya süresi dolmuş | Başlar | Yerleşik demo sertifikasıyla mühürlenir, filigranlı (watermarked: true) | Filigranlı |
Lisans yok, eski bir TRIAL dosyası, Signer içermeyen bir lisans veya sürüm penceresinin dışındaki bir ücretli lisans | Application_Start hata fırlatır; her istek boş bir 500 ile yanıt verir | — | — |
Kural, C# arayüzü ve widget için aynıdır: lisans ücretli bir görüntüleyici lisansı değilse veya geçiciyse çıktı filigranlı olur. Geçici bir lisans altında eklenti her zaman yerleşik demo sertifikasıyla imzalar ve yapılandırdığınız herhangi bir sertifika kullanılmaz.
Demo sertifikası gerçek bir mühür üretir, ancak PDF okuyucularına güvenmez. Bir entegrasyon, değerlendirme lisansı üzerinde uçtan uca oluşturulup test edilebilir; temiz, güvenilir bir çıktı elde etmek için hem ücretli bir lisansa hem de kendi imzalama sertifikasıınıza ihtiyacınız vardır.
C#'dan Kullanım
DocumentSigner, DoconutHost.Initialize tarafından kaydedilir; DoconutHost.Services üzerinden çözün. Yapıcı içsel olduğundan, asla new etmeyin. AddPlugin<SignerPlugin>() olmadan çözümlemek, No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(). fırlatır.
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");
// Mod varsayılan olarak Certified (görünür imza + dijital mühür); WordOutput varsayılan olarak 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, kaynak akışını, uzantısını (".pdf" veya ".docx"), isteği ve sertifikayı bu çağrı için alır. Facade, SignerWidgetOptions.SigningCertificate okumaz; bu ayar widget için geçerlidir. Demo lisansı altında veya Visual modda null geçirin.
SignResult, imzalı belgeyi aranabilir bir akış olarak tutar, ayrıca dosyayı adlandırabilmeniz için Extension (".pdf" veya ".docx") içerir. Akış sizin kontrolünüzde: işiniz bittiğinde onu dispose edin.
MVC 5 denetleyicisinde
Eylemi asenkron yapın ve imzayı await. Bu, sertifika gerektirmeyen bir Visual imzası damgalamaktadır:
[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);
}Bir Word kaynağı, Word çıktısı istemediğiniz sürece PDF'ye imzalanır. Sonucun adını result.Extension üzerinden belirleyin:
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, çağrı başarılı olamadığında döndürmek yerine bir istisna fırlatır:
| İstisna | Mesaj | Ne Zaman |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Sertifikalı mod, ücretli lisans ve hiçbir sertifika gönderilmediğinde |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Sertifikalı mod, geçerlilik süresi dışındaki bir sertifika ile |
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. | Boş PNG baytları veya geçerli olmayan bir yerleştirme |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Diğer herhangi bir kaynak türü |
İmzalama modları, Word çıktısı ve sertifikalar
İmzalama modları
SignRequest.Mode imzanın mühürlenip mühürlenmeyeceğini seçer.
| Mod | Ne üretir | Sertifika | Doğrulanabilir |
|---|---|---|---|
SignatureMode.Certified (varsayılan) | Görünür imza ve bir dijital mühür | Ücretli lisans altında gereklidir | Evet |
SignatureMode.Visual | Yalnızca görünür imza | Hiç gerekmez | Hayır: bir resimdir |
Certified kullanın imzanın kanıtlanabilir olması gerektiğinde: onaylar, sözleşmeler, doğrulayıcının kimlik ve bütünlüğü kontrol etmesi gereken her şey. Visual kullanın yalnızca bir imzanın görünümüne ihtiyacınız olduğunda veya sertifikanız olmadığında. Geçici bir lisans her ikisine de filigran ekler.
PDF mühürleri, RSA veya ECDSA anahtarları için SHA-256 kullanan PKCS#7 ayrık imzalar (adbe.pkcs7.detached)dır. PFX dosyanızda bulunan yayıncı sertifikalarını taşırlar, böylece kök sertifikanıza güvenen bir okuyucu zinciri oluşturabilir. Word‑yerel mühürler OOXML paket imzalarıdır ve yalnızca imzalayanın sertifikasını taşır.
Word belgeleri
.docx kaynağı için, SignRequest.WordOutput çıktıyı seçer. PDF kaynakları için yok sayılır, her zaman bir PDF üretir.
| Çıktı | Ne olur | Doğrulayıcı desteği |
|---|---|---|
WordOutput.Pdf (varsayılan) | Belge PDF'ye dönüştürülür, ardından imzalanır ve mühürlenir | Geniş: imzalı bir PDF her yerde doğrulanır |
WordOutput.Docx | Belge Word olarak kalır: imza resmi içine yerleştirilir, ayrıca bir OOXML paket imzası eklenir | Sınırlı: her görüntüleyici OOXML paket imzalarını göstermez |
Alıcı düzenlenebilir bir Word dosyasına ihtiyaç duymadıkça ve sınırlı doğrulayıcı desteğini kabul ediyorsa PDF tutun.
Sertifika kurulumu
Kendi kimliğinizle mühürlemek için, özel anahtarı içeren bir PFX (PKCS#12) dosyasını eklentiye verin. Widget için SignerWidgetOptions.SigningCertificate ayarlayın; C# arayüzü için sertifikayı SignAsync'a geçirin. Ya baytları ya da bir yolu, ayrıca şifreyi sağlayın. App_Data dosya için iyi bir yerdir, çünkü IIS asla sunmaz:
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'nin özellikleri yalnızca init'tir, bu da C# 7.3 ( .NET Framework projeleri için varsayılan) tarafından ayarlanamaz. Proje dosyasında <LangVersion>'yi 9.0 veya daha yeni bir sürüme ayarlayın.
Sertifika yalnızca bellek içinde tutulur. Asla kaydedilmez, bir istemciye geri gönderilmez veya kalıcı hale getirilmez ve şifre hiçbir zaman bir hata mesajında görünmez.
Gereksinimler:
- PFX / PKCS#12 paket özel anahtarıyla. Yalnızca genel anahtar içeren bir dosya (
.cer,.crt) imza atamaz. Yayıncı zincirini onunla dışa aktarın, böylece PDF mühürleri taşıyabilir. - Doğru şifre.
- Geçerlilik süresi içinde. Süresi dolmuş veya henüz geçerli olmayan bir sertifika uygulamayı durdurmaz, ancak Certified imzalar değiştirilene kadar reddedilir. Visual imzalar etkilenmez.
- Belge imzalama için verilmiş: digital signature veya non-repudiation anahtar kullanımına sahip ve varsa belge imzalama, e-posta koruması veya istemci kimlik doğrulaması sağlayan genişletilmiş anahtar kullanımı. Başka amaçla, örneğin bir TLS sunucu sertifikası olarak verilen bir sertifika yine de imzalar, ancak PDF okuyucular imzayı işaretler.
- Donanım tokenları, akıllı kartlar, HSM'ler ve Windows sertifika deposu desteklenmez. Sertifikayı, özel anahtarı ve zinciriyle birlikte bir PFX dosyasına dışa aktarın.
OpenSSL ile bir sertifikadan ve onun özel anahtarından PFX oluşturun:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# İstediğiniz dışa aktarma şifresi SigningCertificate.Password.Windows sertifika mağazasından bir tane dışa aktarın: certmgr.msc'ı açın ve sertifikayı bulun (özel anahtar mevcut olduğunda simgesi bir anahtar gösterir). Sağ tıklayın, All Tasks → Export… seçeneğini seçin. Yes, export the private key seçeneğini işaretleyin, Personal Information Exchange – PKCS #12 (.PFX) seçin ve bir şifre belirleyin.
Başlangıç Kontrolleri
Widget etkinleştirildiğinde, SignerWidgetOptions.SigningCertificate içindeki sertifika bir kez, DoconutHost.Initialize içinde kontrol edilir, böylece yanlış yapılandırılmış bir PFX ilk imzada değil, başlangıçta başarısız olur. Üç sorun, Application_Start üzerinden bir InvalidOperationException fırlatır ve ardından her istek boş bir 500 yanıt verir; mesaj Windows olay günlüğündedir:
| Mesaj | Düzeltme |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | PfxPath'ı düzeltin; dosyanın dağıtıldığından ve uygulama havuzunun hesabı tarafından okunabildiğinden emin olun |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Parolayı kontrol edin; dosyanın gerçek bir .pfx olduğundan, bir .cer veya .pem olmadığından emin olun |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX'i özel anahtarla tekrar dışa aktarın |
ASP.NET Core'da, ana bilgisayar başlangıçta sertifikayı adlandıran veya süresinin dolduğunu ya da imzalama için verilmediğini belirten bir satır kaydeder. DoconutHost bu satırı yazmaz, bu yüzden .NET Framework'te yeni bir sertifikayı Sertifikalı modda bir test belgesi imzalayarak kontrol edin.
C# arayüzü başlangıçta kontrol edilmez. SignAsync'a gönderdiğiniz sertifika imzaladığınızda okunur, bu yüzden yanlış bir yol ya da parola o çağrıyı başarısız kılar.
Yerleştirilebilir widget
Uç noktaları etkinleştirme
Widget'ın ?sign=open|run|download uç noktaları DocImage.axd tarafından sunulur ve varsayılan olarak kapalıdır. Eklenti kaydının yanına bunları etkinleştirin:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // varsayılan
widget.MaxSignatureImageKb = 512; // varsayılan
// widget.SigningCertificate: Sertifika kurulumuna bakın; demo (su damgalı) imzalama için null bırakın
});
});
// System.Web, Doconut görmeden önce tüm yüklemeyi okur: maxRequestLength (KB) ve
// maxAllowedContentLength (bytes) Web.config içinde widget's MaxUploadMb'nin üzerinde.AddSignerWidget() argüman olmadan widget'ı varsayılanlarla etkinleştirir. Tek başına imzalama yetkisi vermez: AddPlugin<SignerPlugin>() gerekir, aksi takdirde DoconutHost.Initialize fırlatır:
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.Uç noktalar ve betik, Web.config içinde kaydedilen işleyici ve modül tarafından sunulur:
<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>Modül, widget etkin olsun ya da olmasın betiği sunar. AddSignerWidget() olmadan, widget yüklenir ve bırakma bölgesini çizer, ve ilk isteği 404 yanıtını verir: widget daha sonra Signing is not enabled on this server. bildirir
Yükleme limitleri
ASP.NET, DocImage.axd çalışmadan önce tüm istek gövdesini okur. MaxUploadMb üzerindeki ancak ana bilgisayar limitlerinin altında bir yükleme, widget'ın kendi JSON 413 (File is too large.) alır. Ana bilgisayar limitlerinin üzerindeki bir yükleme önce IIS tarafından reddedilir ve widget'ın okuyamadığı bir hata sayfası gösterilir. Her iki ana bilgisayar limitini de widget'ın sınırının üzerinde tutun:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Ana bilgisayar limitlerini aşan, Content-Length (parçalı) olmadan gönderilen bir yükleme de IIS hata sayfasını alır; bu durum için bir çözüm yoktur.
Göm
Betik /doconut-res/js/doconutSigner.js adresinde sunulur. Tek, bağımsız bir dosyadır ve bağımlılıkları yoktur. basePath'yi işleyiciye yönlendirin:
<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) bir CSS seçicisi ya da bir öğe alır, bağlama bulunamazsa hata fırlatır ve bir tutamaç döndürür. Widget'ın varsayılan basePath, /doconut, ASP.NET Core uç noktasındadır; bu paket üzerinde '/DocImage.axd' olmalıdır.
İmzalayan bir PDF veya .docx dosyası yükler, bir imza oluşturur (Çiz bir kanvasta, Yaz bir isim imza yazı tipinde, ya da Görüntü bir PNG, JPG veya GIF'den), sayfaya sürükler ve yeniden boyutlandırır, ardından imzalar ve sonucu indirir. Widget her zaman imzayı PNG olarak gönderir; yüklenen görüntü tarayıcıda 520×160 boyutlarına uyan bir PNG'ye dönüştürülür.
Seçenekler
| Seçenek | Tür | Varsayılan | Notlar |
|---|---|---|---|
basePath | string | '/doconut' | ?sign= uç noktalarının ve ön izleme görüntülerinin sunulduğu yer. Bu paket üzerinde '/DocImage.axd' ayarlayın |
resPath | string | '/doconut-res' | Ayrılmış; widget kendi CSS'sini paketler |
maxUploadMb | number | 25 | Yalnızca istemci tarafı kontrolü, bu yüzden aşırı büyük bir dosya hızlıca başarısız olur. Sunucu sınırı AddSignerWidget içinde MaxUploadMb'dır |
maxSignatureKb | number | 512 | Görüntü modunda istemci tarafı sınırı. Sunucunun MaxSignatureImageKb'ına eşit tutun |
previewWidth | number | 560 | Sayfa ön izlemesinin piksel genişliği |
licenseUrl | string | null | null | Demo-su işareti uyarısını bu URL'ye bir bağlantıya dönüştürür |
signatureMode | string | 'certified' | İlk imza türü: 'certified' veya 'visual'. Başka herhangi bir değer 'certified' olur |
showSignatureModeToggle | boolean | true | Dijital imza / Yalnızca görsel seçeneğini gösterir. false ile widget signatureMode ile imzalar |
wordOutput | string | 'pdf' | .docx kaynakları için ilk çıktı: 'pdf' veya 'docx'. Başka herhangi bir değer 'pdf' olur |
showOutputFormatToggle | boolean | true | PDF / Word seçeneğini gösterir, yalnızca .docx kaynakları için. false ile widget wordOutput kullanır |
labels | object | {} | İngilizce dizelerin herhangi bir alt kümesini geçersiz kılar |
Bir geçişi gizlemek özelliği devre dışı bırakmaz; değeri sabitler. İki yaygın yapılandırma:
// Her iki geçiş de gösterildi, dijital imza varsayılan: tam bir self-service imzalayıcı.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Yalnızca görsel, geçiş yok: dijital imza sunulmayan basit bir damga.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Geri çağrılar
| Geri çağrı | Ne zaman tetiklenir | Yük |
|---|---|---|
onReady | Bağlama sırasında bir kez (reset()'da tekrar tetiklenmez) | — |
onSourceLoaded | Dosya açılır ve ön izlemesi gösterilir | { file: { token, name, pages, ext } } |
onSigned | İmza başarılı olur | { downloadToken, downloadName, watermarked } |
onDownload | Her İndir tıklamasında | { downloadName, downloadToken } |
onError | Açma, imzalama veya indirme adımı başarısız olur ya da Görüntü-modu dosyası çok büyük | { message } |
Bir geri çağrı hata fırlatırsa yakalanır ve kaydedilir; widget akışını asla bozmaz.
Zorunlu tutamaç
| Yöntem | Davranış |
|---|---|
reset() | Bırakma ekranına döner ve mevcut akışı temizler. onReady tekrar tetiklenmez. destroy() sonrası etkisiz. |
loadFile(file) | File ile akışı başlatır. Widget bırakma ekranında değilse etkisiz; gerekirse önce reset() çağırın. |
destroy() | Dinleyicileri kaldırır, bağlamayı boşaltır ve örneği dondurur |
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());Etiketler
Her dize bir İngilizce varsayılanına sahiptir; labels herhangi bir alt kümesini geçersiz kılar ve geri kalanlar İngilizce kalır. Çalışma zamanında değişen parçalar {placeholders} kullanır, örneğin uploading: 'Uploading {name}…' ve pages: '{n} pages'.
| Anahtar | İngilizce varsayılan |
|---|---|
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 |
Diğer anahtarlar yerleştirme adımını, hata ekranını, demo bildiriminin bağlanmış formunu (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) ve aria-live duyurularını kapsar.
open veya run, JSON hatası olmadan 404 yanıtladığında, widget signingNotEnabled gösterir. Sunucudan gelen bir JSON hatası her zaman önceliklidir, bu yüzden süresi dolmuş bir yükleme gibi mesajlar görünür kalır.
Tema
Widget, dsw sınıfını bağlama öğesine ekler ve renklerini, yarıçapını ve yazı tiplerini CSS özel özelliklerinden okur, böylece iç yapısına dokunmadan temalandırabilirsiniz:
#host.dsw {
--dsw-accent: #b0522b; /* bağlantılar, odak, aktif mod */
--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; /* Tip modu */
}Varsayılanlar: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, bir sistem UI yazı tipi ve el yazısı imza yazı tipi.
Kendi ön ucunuzu oluşturun
Widget, DocImage.axd üzerindeki bu HTTP sözleşmesi için bir istemcidir. Rotalar, AddSignerWidget() çağrılana kadar 404 yanıt verir. Hatalar bir JSON gövdesi, { "error": "..." } taşır, tablo "yalnızca durum" dediği yerler hariç. Bilinmeyen bir ?sign= değeri 400 yanıt verir.
| Rota | Amaç | Başarılı yanıt |
|---|---|---|
POST /DocImage.axd?sign=open (çok parçalı, bir dosya) | PDF veya .docx yükleyin ve ön izleme için açın | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON gövdesi) | Yüklenen dosyayı imzalayın | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | İmzalanmış dosyayı akış olarak gönder | 200 — dosya, Content-Disposition: attachment, Cache-Control: no-store |
ext, open yanıtında, baştaki noktayı (".docx") içerir. Sayfa ön izleme, standart görüntüleyici resim rotasını, /DocImage.axd?token={token}&page={n}&thumb=1&width={px} kullanır; gösterilen sayfa placement.page olur.
run gövdesi:
{
"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"
}| Alan | Notlar |
|---|---|
token | open'den gelen token |
signature.kind | Drawn, Typed veya Image, büyük/küçük harfe duyarsız; başka her şey Drawn olur. Sadece bir ipucu: yük her zaman bir PNG'dir |
signature.payload | data: ön eki olmayan çıplak base64 PNG. Gerçek bir PNG olmalı ve çözüldükten sonra MaxSignatureImageKb'dan büyük olmamalıdır |
placement.page | 1 tabanlı |
placement.x / y / w / h | Sol üst köşeden normalize edilmiş 0..1, x + w ≤ 1 ve y + h ≤ 1 ile |
meta.signerName / reason / location | İsteğe bağlı. Her biri kırpılır, boş değer atılır ve her biri 256 karakterde kesilir |
wordOutput | pdf (varsayılan) veya docx; PDF kaynakları için yok sayılır. Başka her şey pdf olur |
mode | certified (varsayılan) veya visual. Başka her şey certified olur |
downloadName çıktıyı izler: <source>-signed.pdf veya <source>-signed.docx, ve download eşleşen Content-Type gönderir.
Yüklenen kaynak ve imzalanmış sonuç her biri 30 dakika saklanır. Bundan sonra, run ve download 404 yanıt verir ve dosya tekrar açılmalıdır. Tüm token'lar GUID'dir.
| Rota | Durum | Ne zaman | Gövde |
|---|---|---|---|
| any | 404 | Widget etkin değil | yalnızca durum |
| any | 405 | Yanlış fiil (open ve run POST gerekir, download GET gerekir) | yalnızca durum |
open | 400 | Çok parçalı yükleme değil | Expected a multipart file upload. |
open | 400 | Dosya yok veya boş | No file uploaded. |
open | 400 | .pdf veya .docx dışındaki her şey | Signing supports PDF and Word (.docx) files only. |
open | 413 | Yükleme MaxUploadMb'ı aşıyor (ancak IIS limitlerini aşmıyor) | File is too large. |
run | 400 | Gövde geçerli bir JSON değil veya boş | Malformed request. / Empty request. |
run | 400 | Token eksik veya GUID değil | Invalid token. |
run | 404 | Yükleme süresi doldu veya hiç açılmadı | Upload expired — please re-open the file. |
run | 400 | İmza yok veya yerleştirme yok | No signature supplied. / No placement supplied. |
run | 400 | Yük base64 değil, boş, çok büyük veya PNG değil | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Yerleştirme sayfanın dışındadır | The signature or its placement is invalid. |
run | 400 | Sertifikalı mod, ücretli lisans ve sertifika yok | No signing certificate configured. |
run | 400 | Sertifikalı mod, geçerlilik süresi dışındaki bir sertifika ile | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | İşleme başarısız | Temizlenmiş bir mesaj |
download | 400 | Token eksik veya GUID değil | yalnızca durum |
download | 404 | Bilinmeyen veya süresi dolmuş token | yalnızca durum |
fetch ile tam bir tur:
// dosya: imzalanacak File; pngBase64: veri: önek olmadan çıplak base64 PNG imzası,
// örneğin canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: dosyayı yükle
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: imzala
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: imzalanmış dosyayı al
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);
}Uç noktalar same-origin'dır: bu sürüm CORS desteği sağlamaz. UI'nizi ve widget betiğini uygulama ile aynı kökenden sunun veya UI'nizin kökeni altında DocImage.axd ve /doconut-res'yi ters proxy yapın.
Üretimde
-
Eklentiyi kurun çekirdek paketinin yanına, aynı sürümde:
Install-Package Doconut.NETFramework.Signer. -
Lisans dosyasını ekleyin.
Doconut.Viewer.Signer.lic'yiDoconut.Viewer.licile aynı klasöre koyun. -
Sertifikanızı bir PFX olarak alın özel anahtarı ve veren zinciriyle birlikte, bir sertifika otoritesinden ya da kuruluşunuzun kendi PKI'sından. İlk olarak denemek için, bir demo lisansı (yerleşik demo sertifikası, filigranlı) ya da kendinden imzalı bir PFX kullanın.
-
Sertifikayı yapılandırmadan okuyun, böylece değiştirildiğinde kodda bir değişiklik yapmaya gerek kalmaz:
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'yiApp_Dataiçinde tutun, IIS'in asla sunmadığı bir konumda, ve şifreyi düz birWeb.configiçinde tutmayın: şifrelenmiş bir yapılandırma bölümü kullanın ya da dağıtımınızın okuduğu bir gizli mağaza. -
Sertifikalı modda bir test belgesi imzalayın. Süresi dolmuş ya da henüz geçerli olmayan bir sertifika
The signing certificate expired on yyyy-MM-dd.(veyais not valid before) ile reddedilir ve bir PDF okuyucu imzaya güvenip güvenmediğini gösterir.
PDF okuyucularına güven. Bir okuyucu, sertifikanın köküne güvendiğinde imzayı geçerli olarak gösterir. Kuruluşunuzun PKI'sı ile bu, kökünüzü güvenen her makinede geçerlidir; bu genellikle kuruluş içindeki tüm makineler demektir. Adobe'un herhangi bir makinede güvendiği sertifikalar (Adobe Approved Trust List) bizim bildiğimiz kadarıyla özel anahtarın bir donanım token'ı ya da HSM'de bulunmasıyla verilir; bu eklenti bunu kullanamaz: yalnızca bir PFX'ten imzalar. Bu tür bir güvene dayanmadan önce sertifika sağlayıcınızla teyit edin.
Web çiftlikleri
Widget, her yüklemeyi ve sonucunu, open'yi sunan sunucunun belleğinde tutar. Yapışkan oturumları olmayan bir yük dengeleyicinin arkasında, daha sonraki bir run, download veya ön izleme isteği başka bir sunucuya ulaşabilir ve yüklemeyi bulamaz. Paylaşılan, şifreli widget deposunu DoconutHost.Initialize'nin ikinci argümanı aracılığıyla kaydedin:
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"; // her sunucunun okuyup yazabileceği bir klasör
store.FarmKey = farmKey; // en az 32 bytes, her sunucuda aynı
// store.Ttl = TimeSpan.FromMinutes(30); // bir yüklemenin ne kadar süre saklandığı (varsayılan)
}));- Tek bir sunucunun hiçbir şeye ihtiyacı yoktur: bu çağrı olmadan bellek içi depo kullanılır.
- Yüklemeler ve sonuçlar paylaşımlı alanda (AES-256, encrypt-then-MAC) dinlenirken şifrelenir ve her dosya token'ına bağlanır, böylece bir token başka bir token'ın dosyasını asla okuyamaz.
FarmKeyen az 32 bayt olmalı ve her sunucuda aynı olmalıdır. Bir gizli mağazadan yükleyin; asla sabit kodlamayın. Kayıt,RootPatheksik olduğunda ya daFarmKey32 bayttan kısa olduğunda birArgumentExceptionfırlatır.RootPath'yi dağıtılmış görüntüleyicinin kullandığı aynı paylaşılan konuma yönlendirin ve her sunucuya aynı imzalama sertifikasını verin.
API referansı
Facade ve widget seçenekleri Doconut ad alanında bulunur; istek ve sonuç tipleri Doconut.Core.Models.Signing içinde bulunur. SignerPlugin, Doconut.Plugins.Signer içinde bulunur.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}DoconutHost.Services üzerinden çözülür; yapıcı internal'dır. sourceExtension, ".pdf" ya da ".docx" olabilir. Ücretli bir lisans altında cert kullanılır ve çıktı temiz olur; geçici bir lisans altında yerleşik demo sertifikası kullanılır, cert yok sayılır ve çıktı su işaretiyle işaretlenmiş olur.
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
}Bir kez yerleştirilen tek bir görünür imza, artı isteğe bağlı imzalayan meta verileri.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes boş değil
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes, her tür için bir PNG'dir. Çizilmiş ya da yazılmış bir imza şeffaftır; yüklenen bir görüntü sahip olduğu şeffaflığı korur, bu yüzden opak bir JPG opak kalır. Kind sadece bir ipucudur.
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 tabanlıdır; X, Y, W ve H, sol üst köşeden normalize edilmiş 0..1'dır.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified varsayılan değerdir
public enum WordOutput { Pdf, Docx } // Pdf varsayılan değerdir; PDF kaynakları için yok sayılırSignResult
public sealed record SignResult(Stream Stream, string Extension);İmzalanmış belge, aranabilir bir akış (stream) olarak ve uzantısı nokta ile birlikte (".pdf" veya ".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 boş değil, ya da PfxPath boş değil
}PfxBytes ya da PfxPath ve ayrıca Password ayarlayın. Ayarlayıcılar yalnızca init'dir: proje C# 9.0 veya daha yeni bir sürüm gerektirir.
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) aracılığıyla ayarlayın; bu, DoconutOptions döndürür, böylece çağrılar zincirlenebilir. Null bir SigningCertificate, geçici bir lisans altında demo sertifikasını ve sadece ücretli bir lisans altında Görsel imzaları ifade eder.
Sorun Giderme
| Semptom | Neden | Çözüm |
|---|---|---|
Eklentiyi ekledikten sonra her istek boş bir 500 döner; olay günlüğü The Signer plugin is registered via AddPlugin but no active license grants Signer. gösterir. | Lisans yok, bir TRIAL dosyası, Signer içermeyen bir lisans veya sürüm penceresinin dışındaki bir ücretli lisans. | Signer sağlayan bir lisans kurun veya AddPlugin<SignerPlugin>() kaldırın. |
Olay günlüğü AddSignerWidget() was called but the Signer plugin is not registered. gösterir. | Widget, eklentisi olmadan etkinleştirilmiş. | options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() ekleyin. |
Olay günlüğü Doconut Signer: the certificate file was not found at '{path}'. gösterir. | PfxPath eksik bir dosyaya işaret ediyor. | Yolu düzeltin; dosyayı uygulama havuzunun hesabının okuyabileceği bir yere dağıtın. |
Olay günlüğü Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. gösterir. | Yanlış şifre veya PKCS#12 dosyası değil. | Şifreyi kontrol edin; gerçek bir .pfx kullanın. |
Olay günlüğü Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. gösterir. | PFX, özel anahtarı olmadan dışa aktarılmış. | Özel anahtarıyla tekrar dışa aktarın. |
new SigningCertificate { … } derlenmiyor. | Proje C# 7.3 kullanıyor, bu sürüm init-only özellikleri ayarlayamaz. | <LangVersion>'yi 9.0 veya daha yeni bir sürüme ayarlayın. |
DocumentSigner çözülürken No IDocumentSigner is registered. hatası atılır. | SignerPlugin kayıtlı değil. | DoconutHost.Initialize içinde AddPlugin<SignerPlugin>() ekleyin. |
| Çıktı su işaretiyle işaretlenmiş. | Lisans geçici (Demo/NFR). | Signer sağlayan bir ücretli lisans kullanın. |
run, 400 No signing certificate configured. yanıtını verir. | Ücretli bir lisans, Sertifikalı mod ve sertifika yok. | SigningCertificate yapılandırın veya Görsel modda imzalayın. |
run, 400 The signing certificate expired on yyyy-MM-dd. yanıtını verir. | Sertifika süresi dolmuş. | Değiştirin; bu arada Görsel imzalar çalışmaya devam eder. |
Widget yükleniyor ancak Signing is not enabled on this server. diyor. | AddSignerWidget() çağrılmadı veya basePath '/DocImage.axd' değil. | AddSignerWidget() çağırın; basePath: '/DocImage.axd' ayarlayın. |
| Büyük bir yükleme, widget mesajı yerine bir IIS hata sayfası gösterir. | maxRequestLength / maxAllowedContentLength, MaxUploadMb'nin altında. | Her iki host limitini de MaxUploadMb üzerine yükseltin. |
run, 400 The signature image must be a PNG., Signature image is not valid base64. veya Signature image is too large. yanıtını verir. | Özel bir UI, bir data: URL'si, bir JPG veya MaxSignatureImageKb'den fazla gönderdi. | Sınırlama içinde çıplak bir base64 PNG gönderin. |
open, 413 File is too large. yanıtını verir. | Yükleme, MaxUploadMb'ı aşıyor. | AddSignerWidget içinde MaxUploadMb artırın; widget'ın maxUploadMb sadece istemci tarafı bir kontrol. |
run veya download, 404 Upload expired — please re-open the file. yanıtını verir. | 30 dakikalık pencere geçti veya çiftlikteki başka bir sunucu yüklemeye sahip değil. | Dosyayı tekrar açın; bir çiftlikte, AddDoconutDistributedWidgets kaydedin. |
İmzalanmış bir .docx, bazı görüntüleyicilerde imza göstermiyor. | Word çıktısı bir OOXML paket imzası taşır, bu da birçok görüntüleyicide gösterilmez. | Varsayılan olarak PDF'ye imzalayın. |
| PDF okuyucular, imzalayanın kimliğinin bilinmediğini söylüyor. | Okuyucu, sertifikanın köküne güvenmiyor (demo sertifikası asla güvenilir değildir). | Okuyucularınızın güvendiği bir kökten bir sertifika kullanın. |
| Widget, UI başka bir kökende olduğunda başarısız olur. | Uç noktalar CORS desteğine sahip değil. | UI'yi aynı kökenden sunun veya DocImage.axd ve /doconut-res için ters proxy yapın. |
| Tema uygulanmıyor. | Seçici, mount içinde bir öğeyi hedefliyor. | Mount'u kendisini hedefleyin: #host.dsw veya #host. |
Çerçeve notları
ASP.NET Core paketleriyle karşılaştırıldığında, bu paket yalnızca barındırma açısından farklıdır; API, uç nokta sözleşmesi, widget betiği ve lisans kuralları aynıdır.
- Kayıt
Application_Startiçinde,DoconutHost.Initializearacılığıyla,builder.Services.AddDoconutyerine yapılır.AddDoconutDistributedWidgetsgibi hizmetler ikinci argümanına gider. - Uç noktalar
DocImage.axdtarafından ve betikDoconutResourceModuletarafından sunulur, her ikisi deWeb.configiçinde kayıtlı,UseDoconut()veUseDoconutResources()yerine. WidgetbasePath: '/DocImage.axd'gerektirir. - Başlangıç hataları her istekte boş bir
500olarak ortaya çıkar, neden Windows olay günlüğünde bulunur. - Yüklemeler ASP.NET tarafından Doconut görmeden önce tamamen okunur, bu yüzden IIS sınırlamaları
MaxUploadMb'nin üzerinde olmalıdır. - Sertifika hakkında başlangıç günlük satırı yok: üç sertifika hatası hâlâ fırlatılır, ancak sertifikayı adlandıran satır yazılmaz.
- C# 9.0 veya daha yeni bir sürüm,
SigningCertificate'nin yalnızca başlatma özelliklerini ayarlamak için gerekir. - Yalnızca Windows, .NET Framework paketinin geri kalanı gibi.
Bu sayfa yardımcı oldu mu?