Πρόσθετο Υπογραφής
Υπογράψτε έγγραφα PDF και Word με ορατή υπογραφή και ψηφιακή σφραγίδα
Το πρόσθετο Signer τοποθετεί μια ορατή υπογραφή σε ένα έγγραφο και, εξ ορισμού, το σφραγιδώνει με μια ψηφιακή υπογραφή που ένας αναγνώστης PDF μπορεί να επαληθεύσει. Υπογράφει PDF και Word (.docx) αρχεία. Η ορατή υπογραφή είναι πάντα μια εικόνα PNG: σχεδιασμένη, πληκτρολογημένη ή ανεβασμένη από τον υπογράφοντα.
| Επίπεδο | Χρησιμοποιήστε το όταν |
|---|---|
DocumentSigner (C#) | Υπογράφετε στον διακομιστή, χωρίς εμπλοκή του προγράμματος περιήγησης |
Drop-in widget (doconutSigner.js) | Θέλετε μια έτοιμη οθόνη ανεβάσματος, υπογραφής και λήψης στη σελίδα σας |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Δημιουργείτε το δικό σας UI υπογραφής με βάση το τεκμηριωμένο συμβόλαιο του διακομιστή |
Κάθε υπογραφή τοποθετείται μία φορά, σε μία σελίδα. Το όνομα του υπογράφοντα, ο λόγος και η τοποθεσία μπορούν να μετακινηθούν μαζί της.
Install the package
Install-Package Doconut.NETFramework.SignerΓια να συνδέσετε το πρόσθετο με την έκδοση που περιγράφεται σε αυτήν την τεκμηρίωση:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Διατηρήστε το πακέτο Signer στην ίδια έκδοση με το Doconut.NETFramework.
Το αρχείο άδειας του πρόσθετου, Doconut.Viewer.Signer.lic, τοποθετείται στον ίδιο φάκελο με το Doconut.Viewer.lic· διαβάζεται μαζί με την άδεια του viewer.
Register the plugin
Όπως κάθε πρόσθετο 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 ώστε η παρασκήνια εργασία να σταματά καθαρά όταν ο app pool επανεκκινείται.
Αυτό είναι ό,τι χρειάζεται η πρόσοψη C#. Το widget και τα HTTP endpoints του είναι μια ξεχωριστή επιλογή, AddSignerWidget() (δείτε Widget ενσωμάτωσης).
Το πρόσθετο χρειάζεται μια άδεια που παρέχει τη δυνατότητα 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). Απορρίπτει για έλλειψη άδειας, αρχείο legacy TRIAL, άδεια χωρίς Signer, ή πληρωμένη άδεια που χρησιμοποιείται εκτός του χρονικού πλαισίου της. Προσωρινές άδειες Demo/NFR γίνονται αποδεκτές. Δείτε Ρύθμιση Άδειας.
Licensing & watermark
| Κατάσταση άδειας | Έναρξη | Πιστοποιημένη υπογραφή | Οπτική υπογραφή |
|---|---|---|---|
Paid license granting Signer, certificate configured | Ξεκινά | Σφραγιδωμένο με το πιστοποιητικό σας, καθαρό (watermarked: false) | Καθαρό |
Paid license granting Signer, no certificate | Ξεκινά | Απορρίφθηκε: No signing certificate configured. | Καθαρό |
| Paid license, certificate expired or not yet valid | Ξεκινά | Απορρίφθηκε: The signing certificate expired on yyyy-MM-dd. | Καθαρό |
| Temporary Demo/NFR license, active or expired | Ξεκινά | Σφραγιδωμένο με το ενσωματωμένο demo πιστοποιητικό, με υδατογράφημα (watermarked: true) | Με υδατογράφημα |
No license, a legacy TRIAL file, a license without Signer, or a paid license outside its version window | Application_Start απορρίπτει· κάθε αίτηση επιστρέφει ένα κενό 500 | — | — |
Ο κανόνας είναι ο ίδιος για την πρόσοψη C# και το widget: η έξοδος είναι με υδατογράφημα όταν η άδεια δεν είναι πληρωμένη άδεια viewer ή είναι προσωρινή. Με μια προσωρινή άδεια το πρόσθετο πάντα υπογράφει με το ενσωματωμένο demo πιστοποιητικό, και οποιοδήποτε πιστοποιητικό ρυθμίσετε δεν χρησιμοποιείται.
Το demo πιστοποιητικό παράγει μια γνήσια σφραγίδα, αλλά οι αναγνώστες 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· αυτή η ρύθμιση είναι για το widget. Περνάτε null υπό άδεια demo, ή σε λειτουργία 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. | Κατάσταση πιστοποιημένη, πληρωμένη άδεια, και δεν παρεχθεί πιστοποιητικό |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Κατάσταση πιστοποιημένη με πιστοποιητικό εκτός του χρονικού του παραθύρου |
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. | Κενά bytes 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) που περιλαμβάνει το ιδιωτικό κλειδί. Για το widget, ορίστε SignerWidgetOptions.SigningCertificate· για τη διεπαφή C#, περάστε το πιστοποιητικό στο SignAsync. Παρέχετε είτε τα byte είτε μια διαδρομή, συν τον κωδικό πρόσβασης. Το 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, κάτι που το C# 7.3 (η προεπιλογή για έργα .NET Framework) δεν μπορεί να ορίσει. Ορίστε το <LangVersion> σε 9.0 ή νεότερο στο αρχείο έργου.
Το πιστοποιητικό διατηρείται μόνο στη μνήμη. Δεν καταγράφεται ποτέ, δεν επιστρέφεται σε πελάτη, ούτε αποθηκεύεται, και ο κωδικός πρόσβασης δεν εμφανίζεται ποτέ σε μήνυμα σφάλματος.
Απαιτήσεις:
- Ένα πακέτο PFX / PKCS#12 με το ιδιωτικό του κλειδί. Ένα αρχείο μόνο με δημόσιο κλειδί (
.cer,.crt) δεν μπορεί να υπογράψει. Εξάγετε την αλυσίδα εκδότη μαζί του, ώστε οι σφραγίδες PDF να τη μεταφέρουν. - Ο σωστός κωδικός πρόσβασης.
- Μέσα στο χρονικό παράθυρο ισχύος του. Ένα ληγμένο ή ακόμη μη έγκυρο πιστοποιητικό δεν σταματά την εφαρμογή, αλλά οι υπογραφές Certified απορρίπτονται μέχρι να αντικατασταθεί. Οι υπογραφές Visual δεν επηρεάζονται.
- Εκδομένο για υπογραφή εγγράφων: χρήση κλειδιού με digital signature ή non-repudiation, και εκτεταμένη χρήση κλειδιού, εάν υπάρχει, που επιτρέπει την υπογραφή εγγράφων, προστασία email ή έλεγχο ταυτότητας πελάτη. Ένα πιστοποιητικό εκδοθέν για κάτι άλλο, όπως πιστοποιητικό διακομιστή TLS, εξακολουθεί να υπογράφει, αλλά οι αναγνώστες PDF σηματοδοτούν την υπογραφή.
- Οι υλικοί διακριτικοί κώδικες, οι έξυπνες κάρτες, τα HSM και το αποθετήριο πιστοποιητικών των 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) και ορίστε έναν κωδικό πρόσβασης.
Έλεγχοι εκκίνησης
Όταν το widget είναι ενεργοποιημένο, το πιστοποιητικό στο 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 διαβάζεται όταν υπογράφετε, έτσι ένα λανθασμένο μονοπάτι ή κωδικός πρόσβασης αποτυγχάνει αυτή την κλήση.
Ενσωματωμένο widget
Ενεργοποίηση των τελικών σημείων
Τα ?sign=open|run|download τελικά σημεία του widget εξυπηρετούνται από το DocImage.axd και είναι απενεργοποιημένο από προεπιλογή. Ενεργοποιήστε τα δίπλα στην καταγραφή του plugin:
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() χωρίς όρισμα ενεργοποιεί το widget με τις προεπιλογές. Δεν παρέχει υπογραφή από μόνο του: χρειάζεται το 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.Τα τελικά σημεία και το script εξυπηρετούνται από τον handler και το module που είναι καταχωρημένο στο 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>Το module εξυπηρετεί το script είτε το widget είναι ενεργοποιημένο είτε όχι. Χωρίς το AddSignerWidget(), το widget φορτώνει και σχεδιάζει τη ζώνη απόθεσής του, και η πρώτη του αίτηση απαντά με 404: το widget τότε αναφέρει Signing is not enabled on this server.
Όρια μεταφόρτωσης
Το ASP.NET διαβάζει ολόκληρο το σώμα της αίτησης πριν εκτελεστεί το DocImage.axd. Μια μεταφόρτωση πάνω από MaxUploadMb αλλά κάτω από τα όρια του κεντρικού συστήματος λαμβάνει το δικό του JSON του widget 413 (File is too large.). Μια μεταφόρτωση πάνω από τα όρια του κεντρικού συστήματος απορρίπτεται πρώτα από το IIS, με μια σελίδα σφάλματος που το widget δεν μπορεί να διαβάσει. Διατηρήστε και τα δύο όρια του κεντρικού συστήματος πάνω από το όριο του widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Μια μεταφόρτωση που αποστέλλεται χωρίς Content-Length (chunked) και υπερβαίνει τα όρια του κεντρικού συστήματος λαμβάνει επίσης τη σελίδα σφάλματος του IIS· δεν υπάρχει λύση για αυτή την περίπτωση.
Ενσωμάτωση
Το script εξυπηρετείται στο /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 selector ή ένα στοιχείο, ρίχνει σφάλμα αν δεν βρεθεί το mount, και επιστρέφει ένα handle. Η προεπιλεγμένη basePath του widget, /doconut, είναι το endpoint του ASP.NET Core· σε αυτό το πακέτο πρέπει να είναι '/DocImage.axd'.
Ο υπογράφων ανεβάζει ένα αρχείο PDF ή .docx, δημιουργεί μια υπογραφή (Draw σε καμβά, Type ένα όνομα με γραμματοσειρά υπογραφής, ή Image από PNG, JPG ή GIF), το σύρει και αλλάζει το μέγεθός του στη σελίδα, και υπογράφει και κατεβάζει το αποτέλεσμα. Το widget στέλνει πάντα την υπογραφή ως PNG· μια ανεβασμένη εικόνα μετατρέπεται στον περιηγητή σε PNG που ταιριάζει στο 520×160.
Επιλογές
| Επιλογή | Τύπος | Προεπιλογή | Σημειώσεις |
|---|---|---|---|
basePath | string | '/doconut' | Πού εξυπηρετούνται τα endpoints και οι εικόνες προεπισκόπησης του ?sign=. Ορίστε το '/DocImage.axd' σε αυτό το πακέτο |
resPath | string | '/doconut-res' | Κρατημένο· το widget περιλαμβάνει το δικό του CSS |
maxUploadMb | number | 25 | Έλεγχος μόνο στην πλευρά του πελάτη, έτσι ένα υπερμεγέθες αρχείο αποτυγχάνει γρήγορα. Το όριο του διακομιστή είναι MaxUploadMb στο AddSignerWidget |
maxSignatureKb | number | 512 | Όριο στην πλευρά του πελάτη για τη λειτουργία Image. Κρατήστε το ίσο με το MaxSignatureImageKb του διακομιστή |
previewWidth | number | 560 | Πλάτος σε pixel της προεπισκόπησης σελίδας |
licenseUrl | string | null | null | Μετατρέπει την ειδοποίηση demo-watermark σε σύνδεσμο προς αυτό το URL |
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 | {} | Αντικαθιστά οποιοδήποτε υποσύνολο των αγγλικών κειμένων |
Η απόκρυψη ενός toggle δεν απενεργοποιεί τη λειτουργία· καθορίζει την τιμή. Δύο κοινές ρυθμίσεις:
// Και οι δύο διακόπτες εμφανίζονται, η ψηφιακή υπογραφή είναι προεπιλεγμένη: ένας πλήρης αυτό-εξυπηρετούμενος υπογράφων.
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 | Σε κάθε κλικ στο Download | { downloadName, downloadToken } |
onError | Αποτυγχάνει ένα βήμα ανοίγματος, υπογραφής ή λήψης, ή ένα αρχείο σε λειτουργία Image είναι πολύ μεγάλο | { message } |
Μια κλήση που ρίχνει σφάλμα παγιδεύεται και καταγράφεται· δεν διακόπτει ποτέ τη ροή του widget.
Αυτοσχέδης χειρισμός
| Μέθοδος | Συμπεριφορά |
|---|---|
reset() | Επιστρέφει στην οθόνη drop και καθαρίζει την τρέχουσα ροή. Δεν ενεργοποιεί ξανά το onReady. Δεν κάνει τίποτα μετά το destroy() |
loadFile(file) | Ξεκινά τη ροή με ένα File. Δεν κάνει τίποτα εκτός αν το widget βρίσκεται στην οθόνη drop· καλέστε πρώτα το reset() αν χρειάζεται |
destroy() | Αφαιρεί τους listeners, αδειάζει το 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, το widget εμφανίζει το signingNotEnabled. Ένα σφάλμα JSON από τον διακομιστή πάντα προτεραιότητα, έτσι μηνύματα όπως η λήξη του ανεβασμένου αρχείου παραμένουν ορατά.
Θεματοποίηση
Το widget προσθέτει την κλάση 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 και μια πλάγια γραμματοσειρά υπογραφής.
Δημιουργήστε το δικό σας frontend
Το widget είναι ένας πελάτης για αυτή τη σύμβαση 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 | Το token από open |
signature.kind | Drawn, Typed ή Image, χωρίς διάκριση πεζών‑κεφαλαίων· οτιδήποτε άλλο γίνεται Drawn. Μόνο υπόδειξη: το payload είναι πάντα 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 και το αρχείο πρέπει να ανοίξει ξανά. Όλα τα tokens είναι GUIDs.
| Διαδρομή | Κατάσταση | Πότε | Σώμα |
|---|---|---|---|
| any | 404 | Το widget δεν είναι ενεργοποιημένο | μόνο κατάσταση |
| any | 405 | Λάθος μέθοδος (open και run χρειάζονται POST, download χρειάζεται GET) | μόνο κατάσταση |
open | 400 | Δεν είναι multipart ανέβασμα | 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 | Το token λείπει ή δεν είναι GUID | Invalid token. |
run | 404 | Το ανέβασμα έληξε ή δεν ανοίχθηκε ποτέ | Upload expired — please re-open the file. |
run | 400 | Δεν υπάρχει υπογραφή ή δεν υπάρχει τοποθέτηση | No signature supplied. / No placement supplied. |
run | 400 | Το payload δεν είναι 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 | Το token λείπει ή δεν είναι GUID | μόνο κατάσταση |
download | 404 | Άγνωστο ή ληγμένο token | μόνο κατάσταση |
Μια πλήρης διαδρομή με fetch:
// file: το File για υπογραφή; pngBase64: η υπογραφή ως ακατέργαστο base64 PNG, χωρίς πρόθεμα data:,
// για παράδειγμα canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: ανεβάστε το αρχείο
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: υπογράψτε το
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: κατεβάστε το υπογεγραμμένο αρχείο
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}Τα σημεία πρόσβασης είναι same-origin: αυτή η έκδοση δεν υποστηρίζει CORS. Σερβίρετε το UI σας και το script του widget από την ίδια προέλευση με την εφαρμογή, ή κάντε reverse-proxy τα DocImage.axd και /doconut-res κάτω από την προέλευση του UI σας.
Σε παραγωγή
-
Εγκαταστήστε το plugin δίπλα στο βασικό πακέτο, στην ίδια έκδοση:
Install-Package Doconut.NETFramework.Signer. -
Προσθέστε το αρχείο άδειας. Τοποθετήστε το
Doconut.Viewer.Signer.licστον ίδιο φάκελο με τοDoconut.Viewer.lic. -
Αποκτήστε το πιστοποιητικό σας ως PFX με το ιδιωτικό κλειδί και την αλυσίδα εκδότη, από μια αρχή πιστοποίησης ή το δικό σας PKI του οργανισμού. Για να δοκιμάσετε πρώτα, χρησιμοποιήστε μια demo άδεια (το ενσωματωμένο demo πιστοποιητικό, με υδατογράφημα) ή ένα αυτο-υπογεγραμμένο 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) είναι, όσο γνωρίζουμε, εκδοθέντα με το ιδιωτικό κλειδί σε ένα hardware token ή HSM, το οποίο αυτό το plugin δεν μπορεί να χρησιμοποιήσει: υπογράφει μόνο από ένα PFX. Επιβεβαιώστε με τον πάροχο του πιστοποιητικού σας πριν βασιστείτε σε αυτό το είδος εμπιστοσύνης.
Δίκτυα Web
Το widget διατηρεί κάθε ανέβασμα και το αποτέλεσμα του στη μνήμη του διακομιστή που σερβίρισε το open. Πίσω από έναν φορτωτή ισορροπίας χωρίς sticky sessions, ένα μεταγενέστερο run, download ή αίτημα προεπισκόπησης μπορεί να φτάσει σε άλλο διακομιστή και να μην βρει το ανέβασμα. Καταχωρίστε το κοινόχρηστο, κρυπτογραφημένο κατάστημα widget μέσω του δεύτερου ορίσματος του 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 byte, ίδιο σε κάθε διακομιστή
// store.Ttl = TimeSpan.FromMinutes(30); // πόσο διαρκεί η αποθήκευση ενός ανεβάσματος (η προεπιλογή)
}));- Ένας μόνος διακομιστής δεν χρειάζεται τίποτα: χωρίς αυτήν την κλήση χρησιμοποιείται το κατάστημα στη μνήμη.
- Τα ανεβάσματα και τα αποτελέσματα κρυπτογραφούνται κατά την αποθήκευση στο κοινόχρηστο (AES-256, encrypt-then-MAC), και κάθε αρχείο συνδέεται με το token του, ώστε ένα token να μην μπορεί ποτέ να διαβάσει το αρχείο κάποιου άλλου.
- Το
FarmKeyπρέπει να είναι τουλάχιστον 32 byte και το ίδιο σε κάθε διακομιστή. Φορτώστε το από ένα κατάστημα μυστικών· μην το κωδικοποιείτε σκληρά. Η καταχώριση ρίχνει έναArgumentExceptionόταν τοRootPathλείπει ή τοFarmKeyείναι μικρότερο από 32 byte. - Κατευθύνετε το
RootPathστην ίδια κοινόχρηστη τοποθεσία που χρησιμοποιεί ο κατανεμημένος viewer, και δώστε σε κάθε διακομιστή το ίδιο πιστοποιητικό υπογραφής.
Αναφορά API
Η πρόσοψη και οι επιλογές του widget βρίσκονται στον χώρο ονομάτων 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 και η έξοδος είναι καθαρή· με προσωρινή άδεια χρησιμοποιείται το ενσωματωμένο demo πιστοποιητικό, το 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. Οι setters είναι μόνο 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 ώστε οι κλήσεις να μπορούν να αλυσιδωθούν. Ένα null SigningCertificate σημαίνει το demo πιστοποιητικό με προσωρινή άδεια, και οι Visual υπογραφές μόνο με πληρωμένη άδεια.
Επίλυση προβλημάτων
| Συμπτωμα | Αιτία | Διόρθωση |
|---|---|---|
Κάθε αίτηση επιστρέφει ένα κενό 500 μετά την προσθήκη του plugin· το αρχείο καταγραφής συμβάντων δείχνει 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. | Το widget είναι ενεργοποιημένο χωρίς το plugin του | Προσθέστε το 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 |
| Η έξοδος έχει υδατογράφημα | Η άδεια είναι προσωρινή (Demo/NFR) | Χρησιμοποιήστε μια πληρωμένη άδεια που παρέχει Signer |
run απαντά 400 No signing certificate configured. | Πληρωμένη άδεια, λειτουργία Certified, και χωρίς πιστοποιητικό | Ρυθμίστε το SigningCertificate, ή υπογράψτε σε λειτουργία Visual |
run απαντά 400 The signing certificate expired on yyyy-MM-dd. | Το πιστοποιητικό είναι παλιό | Αντικαταστήστε το· οι Visual υπογραφές συνεχίζουν να λειτουργούν εν τω μεταξύ |
Το widget φορτώνει αλλά εμφανίζει Signing is not enabled on this server. | Το AddSignerWidget() δεν κλήθηκε, ή το basePath δεν είναι '/DocImage.axd' | Καλέστε το AddSignerWidget()· ορίστε το basePath: '/DocImage.axd' |
| Μια μεγάλη μεταφόρτωση εμφανίζει μια σελίδα σφάλματος IIS αντί για το μήνυμα του widget | maxRequestLength / maxAllowedContentLength είναι κάτω από MaxUploadMb | Αυξήστε και τα δύο όρια του host πάνω από 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 | Στείλτε ένα ακατέργαστο base64 PNG εντός του ορίου |
open απαντά 413 File is too large. | Η μεταφόρτωση υπερβαίνει το MaxUploadMb | Αυξήστε το MaxUploadMb στο AddSignerWidget· το maxUploadMb του widget είναι μόνο έλεγχος στην πλευρά του πελάτη |
run ή download απαντά 404 Upload expired — please re-open the file. | Το παράθυρο των 30 λεπτών έληξε, ή ένας άλλος διακομιστής στη φάρμα δεν έχει τη μεταφόρτωση | Ανοίξτε ξανά το αρχείο· σε φάρμα, καταχωρίστε το AddDoconutDistributedWidgets |
Ένα υπογεγραμμένο .docx δεν εμφανίζει υπογραφή σε ορισμένους προβολείς | Η έξοδος Word περιέχει υπογραφή πακέτου OOXML, την οποία πολλοί προβολείς δεν εμφανίζουν | Υπογράψτε σε PDF, το προεπιλεγμένο |
| Οι αναγνώστες PDF λένε ότι η ταυτότητα του υπογράφοντα είναι άγνωστη | Ο αναγνώστης δεν εμπιστεύεται τη ρίζα του πιστοποιητικού (το demo πιστοποιητικό δεν εμπιστεύεται ποτέ) | Χρησιμοποιήστε ένα πιστοποιητικό από ρίζα που εμπιστεύονται οι αναγνώστες σας |
| Το widget αποτυγχάνει όταν το UI βρίσκεται σε διαφορετική προέλευση | Τα endpoints δεν έχουν υποστήριξη CORS | Σερβίρετε το UI από την ίδια προέλευση, ή κάντε reverse-proxy τα DocImage.axd και /doconut-res |
| Το θέμα δεν εφαρμόζεται | Ο selector στοχεύει σε στοιχείο μέσα στο mount | Στοχεύστε στο ίδιο το mount: #host.dsw ή #host |
Σημειώσεις πλαισίου
Σε σύγκριση με τα πακέτα ASP.NET Core, αυτό το πακέτο διαφέρει μόνο στο hosting· το API, το συμβόλαιο του endpoint, το script του widget και οι κανόνες αδειοδότησης είναι τα ίδια.
- Καταχώρηση βρίσκεται στο
Application_Start, μέσωDoconutHost.Initialize, αντί γιαbuilder.Services.AddDoconut. Υπηρεσίες όπωςAddDoconutDistributedWidgetsπηγαίνουν στο δεύτερο όρισμά του. - Τελικά σημεία εξυπηρετούνται από
DocImage.axdκαι το script απόDoconutResourceModule, και τα δύο καταχωρούνται στοWeb.config, αντί γιαUseDoconut()καιUseDoconutResources(). Το widget χρειάζεταιbasePath: '/DocImage.axd'. - Αποτυχίες εκκίνησης εμφανίζονται ως ένα κενό
500σε κάθε αίτημα, με τον λόγο στο αρχείο συμβάντων των Windows. - Ανεβάσματα διαβάζονται πλήρως από το ASP.NET πριν τα δει το Doconut, έτσι τα όρια του IIS πρέπει να είναι πάνω από
MaxUploadMb. - Καμία γραμμή καταγραφής εκκίνησης σχετικά με το πιστοποιητικό: τα τρία σφάλματα πιστοποιητικού εξακολουθούν να ρίχνονται, αλλά η γραμμή που ονομάζει το πιστοποιητικό δεν γράφεται.
- C# 9.0 ή νεότερη απαιτείται για να ορίσετε τις ιδιότητες μόνο‑αρχικοποίησης του
SigningCertificate. - Μόνο Windows, όπως το υπόλοιπο του πακέτου .NET Framework.
Ήταν αυτή η σελίδα χρήσιμη;