Wtyczka Signer
Podpisuj dokumenty PDF i Word z widocznym podpisem oraz cyfrową pieczęcią
Wtyczka Signer umieszcza widoczny podpis na dokumencie i domyślnie zabezpiecza go cyfrowym podpisem, który może zweryfikować czytnik PDF. Podpisuje PDF i Word (.docx). Widoczny podpis jest zawsze obrazem PNG: narysowany, wpisany lub przesłany przez podpisującego.
| Powierzchnia | Kiedy używać |
|---|---|
DocumentSigner (C#) | Podpisujesz na serwerze, bez udziału przeglądarki |
Drop-in widget (doconutSigner.js) | Chcesz gotowy ekran przesyłania, podpisywania i pobierania na swojej stronie |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Budujesz własny interfejs podpisywania zgodnie z udokumentowanym kontraktem serwera |
Każdy podpis jest umieszczany raz, na jednej stronie. Imię i nazwisko podpisującego, powód oraz lokalizacja mogą towarzyszyć mu.
Instalacja pakietu
Install-Package Doconut.NETFramework.SignerAby przypiąć wtyczkę do wersji opisanej w tej dokumentacji:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Utrzymuj pakiet Signer w tej samej wersji co Doconut.NETFramework.
Plik licencji wtyczki, Doconut.Viewer.Signer.lic, znajduje się w tym samym folderze co Doconut.Viewer.lic; jest odczytywany razem z licencją przeglądarki.
Rejestracja wtyczki
Podobnie jak każda wtyczka Doconut, Signer rejestruje się w AddPlugin<TPlugin>() w DoconutHost.Initialize, wywoływanym z Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Dodaj Doconut.DoconutHost.Shutdown() do Application_End, aby prace w tle kończyły się czysto przy recyklingu puli aplikacji.
To wszystko, czego potrzebuje fasada C#. Widget i jego endpointy HTTP to oddzielna opcja, AddSignerWidget() (zobacz Widget wbudowany).
Wtyczka wymaga licencji, która zapewnia możliwość Signer. Bez niej, DoconutHost.Initialize zgłasza wyjątek z 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.W System.Web oznacza to, że każde żądanie zwraca pusty 500, a przyczyna jest dostępna tylko w dzienniku zdarzeń Windows (źródło ASP.NET). Zgłasza wyjątek przy braku licencji, starszym pliku TRIAL, licencji bez Signer oraz płatnej licencji użytej poza okresem jej wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Konfiguracja licencji.
Licencjonowanie i znak wodny
| Stan licencji | Uruchomienie | Podpis certyfikowany | Podpis wizualny |
|---|---|---|---|
Płatna licencja przyznająca Signer, certyfikat skonfigurowany | Uruchamia się | Zabezpieczony Twoim certyfikatem, czysty (watermarked: false) | Czysty |
Płatna licencja przyznająca Signer, bez certyfikatu | Uruchamia się | Odrzucony: No signing certificate configured. | Czysty |
| Płatna licencja, certyfikat wygasły lub jeszcze nieważny | Uruchamia się | Odrzucony: The signing certificate expired on yyyy-MM-dd. | Czysty |
| Tymczasowa licencja Demo/NFR, aktywna lub wygasła | Uruchamia się | Zabezpieczony wbudowanym certyfikatem demo, znakowany (watermarked: true) | Znakowany |
Brak licencji, starszy plik TRIAL, licencja bez Signer, lub płatna licencja poza okresem wersji | Application_Start zgłasza wyjątek; każde żądanie zwraca pusty 500 | — | — |
Zasada jest taka sama dla fasady C# i widgetu: wynik jest znakowany, gdy licencja nie jest płatną licencją przeglądarki lub jest tymczasowa. Podczas tymczasowej licencji wtyczka zawsze podpisuje się wbudowanym certyfikatem demo, a każdy skonfigurowany przez Ciebie certyfikat nie jest używany.
Certyfikat demo tworzy prawdziwą pieczęć, ale czytniki PDF go nie ufają. Integrację można zbudować i przetestować end‑to‑end na licencji ewaluacyjnej; aby uzyskać czysty, zaufany wynik, potrzebujesz zarówno płatnej licencji, jak i własnego certyfikatu podpisu.
Użycie z C#
DocumentSigner jest rejestrowany przez DoconutHost.Initialize; rozwiąż go z DoconutHost.Services. Jego konstruktor jest wewnętrzny, więc nigdy nie new go. Rozwiązywanie go bez AddPlugin<SignerPlugin>() rzuca 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");
// Tryb domyślnie ustawiony na Certified (widoczny podpis + cyfrowa pieczęć); WordOutput domyślnie ustawiony na 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 przyjmuje strumień źródłowy, jego rozszerzenie (".pdf" lub ".docx"), żądanie oraz certyfikat dla tego wywołania. Fasada nie odczytuje SignerWidgetOptions.SigningCertificate; to ustawienie jest przeznaczone dla widgetu. Przekaż null w ramach licencji demo lub w trybie Visual.
SignResult przechowuje podpisany dokument jako strumień z możliwością przewijania, plus jego Extension (".pdf" lub ".docx"), abyś mógł nazwać plik. Właścicielem jest strumień: zwolnij go, gdy skończysz.
W kontrolerze MVC 5
Uczyń akcję asynchroniczną i await sygnaturę. Ta nakłada podpis Visual, który nie wymaga certyfikatu:
[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);
}Źródło Word jest podpisywane do PDF, chyba że poprosisz o wyjście Word. Nazwij wynik z 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 rzuca wyjątek zamiast zwracać, gdy wywołanie nie może się powieść:
| Wyjątek | Komunikat | Kiedy |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Tryb certyfikowany, płatna licencja i brak przekazanego certyfikatu |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Tryb certyfikowany z certyfikatem poza okresem ważności |
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. | Puste bajty PNG lub umieszczenie, które nie jest prawidłowe |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Dowolny inny typ źródła |
Tryby podpisywania, wyjście Word i certyfikaty
Tryby podpisywania
SignRequest.Mode wybiera, czy podpis jest uszczelniony.
| Tryb | Co produkuje | Certyfikat | Weryfikowalny |
|---|---|---|---|
SignatureMode.Certified (domyślnie) | Widoczny podpis plus cyfrowa pieczęć | Wymagany przy płatnej licencji | Tak |
SignatureMode.Visual | Tylko widoczny podpis | Nigdy nie potrzebny | Nie: to jest obraz |
Użyj Certified, gdy podpis musi być udowodniony: zatwierdzenia, umowy, wszystko, co weryfikator musi sprawdzić pod kątem tożsamości i integralności. Użyj Visual, gdy potrzebny jest jedynie wygląd podpisu lub nie masz certyfikatu. Tymczasowa licencja dodaje znak wodny do obu.
Pieczęcie PDF są odłączonymi podpisami PKCS#7 (adbe.pkcs7.detached) z SHA-256, dla kluczy RSA lub ECDSA. Zawierają certyfikaty wystawcy znajdujące się w Twoim pliku PFX, więc czytnik, który ufa Twojemu korzeniowi, może zbudować łańcuch. Pieczęcie natywne dla Word są podpisami pakietu OOXML i zawierają tylko certyfikat podpisującego.
Dokumenty Word
Dla źródła .docx, SignRequest.WordOutput wybiera wyjście. Jest ignorowane dla źródeł PDF, które zawsze generują PDF.
| Wyjście | Co się dzieje | Obsługa weryfikatora |
|---|---|---|
WordOutput.Pdf (domyślnie) | Dokument jest konwertowany do PDF, a następnie podpisywany i uszczelniany | Szeroka: podpisany PDF weryfikuje się wszędzie |
WordOutput.Docx | Dokument pozostaje w formacie Word: obraz podpisu jest wstawiany, plus podpis pakietu OOXML | Ograniczona: nie każdy podgląd wyświetla podpisy pakietu OOXML |
Zachowaj PDF, chyba że odbiorca potrzebuje edytowalnego pliku Word i akceptuje ograniczoną obsługę weryfikatora.
Konfiguracja certyfikatu
Aby uszczelnić własną tożsamością, podaj wtyczce plik PFX (PKCS#12) zawierający klucz prywatny. Dla widgetu ustaw SignerWidgetOptions.SigningCertificate; dla fasady C# przekaż certyfikat do SignAsync. Podaj albo bajty, albo ścieżkę, plus hasło. App_Data jest dobrym miejscem na plik, ponieważ IIS nigdy go nie udostępnia:
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"] ?? "",
};
});
});Właściwości SigningCertificate są tylko inicjalizowane, co C# 7.3 (domyślne dla projektów .NET Framework) nie może ustawić. Ustaw <LangVersion> na 9.0 lub nowszy w pliku projektu.
Certyfikat jest przechowywany wyłącznie w pamięci. Nigdy nie jest logowany, zwracany klientowi ani zapisywany, a hasło nigdy nie pojawia się w komunikacie o błędzie.
Wymagania:
- Pakiet PFX / PKCS#12 z kluczem prywatnym. Plik zawierający tylko klucz publiczny (
.cer,.crt) nie może podpisywać. Wyeksportuj łańcuch wystawcy razem z nim, aby pieczęcie PDF mogły go zawierać. - Poprawne hasło.
- W jego oknie ważności. Wygasły lub jeszcze nieważny certyfikat nie zatrzymuje aplikacji, ale podpisy Certified są odrzucane, dopóki nie zostaną wymienione. Podpisy Visual pozostają bez zmian.
- Wydany do podpisywania dokumentów: użycie klucza z digital signature lub non-repudiation, oraz rozszerzone użycie klucza, jeśli istnieje, które zezwala na podpisywanie dokumentów, ochronę e‑mail lub uwierzytelnianie klienta. Certyfikat wydany do innego celu, np. certyfikat serwera TLS, nadal może podpisywać, ale czytniki PDF oznaczają taki podpis.
- Tokeny sprzętowe, karty inteligentne, HSM i magazyn certyfikatów Windows nie są obsługiwane. Wyeksportuj certyfikat wraz z kluczem prywatnym i łańcuchem do PFX.
Utwórz PFX z certyfikatu i jego klucza prywatnego przy użyciu OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Hasło eksportu, o które jesteś pytany, to SigningCertificate.Password.Wyeksportuj go z magazynu certyfikatów Windows: otwórz certmgr.msc i znajdź certyfikat (ikona pokazuje klucz, gdy klucz prywatny jest dostępny). Kliknij prawym przyciskiem, wybierz All Tasks → Export…, zaznacz Yes, export the private key, wybierz Personal Information Exchange – PKCS #12 (.PFX) i ustaw hasło.
Kontrole uruchamiania
Gdy widget jest włączony, certyfikat w SignerWidgetOptions.SigningCertificate jest sprawdzany raz, wewnątrz DoconutHost.Initialize, więc nieprawidłowo skonfigurowany PFX powoduje błąd przy uruchamianiu, a nie przy pierwszym podpisie. Trzy problemy zgłaszają InvalidOperationException z Application_Start, a każde żądanie zwraca pusty 500; komunikat znajduje się w dzienniku zdarzeń Windows:
| Komunikat | Rozwiązanie |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Popraw PfxPath; upewnij się, że plik jest wdrożony i czytelny dla konta puli aplikacji |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Sprawdź hasło; upewnij się, że plik jest prawdziwym .pfx, a nie .cer ani .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Wyeksportuj ponownie PFX z kluczem prywatnym |
W ASP.NET Core host również zapisuje jedną linię przy uruchamianiu, podając nazwę certyfikatu lub ostrzeżenie, że jest wygasły lub nie wydany do podpisywania. DoconutHost nie zapisuje tej linii, więc w .NET Framework sprawdź nowy certyfikat, podpisując dokument testowy w trybie Certified.
Fasada C# nie jest sprawdzana przy uruchamianiu. Certyfikat, który przekazujesz do SignAsync, jest odczytywany w momencie podpisywania, więc nieprawidłowa ścieżka lub hasło powodują błąd tego wywołania.
Widget typu Drop‑in
Włączenie punktów końcowych
Punkty końcowe ?sign=open|run|download widgetu są obsługiwane przez DocImage.axd i są wyłączone domyślnie. Włącz je obok rejestracji wtyczki:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // wartość domyślna
widget.MaxSignatureImageKb = 512; // wartość domyślna
// widget.SigningCertificate: zobacz konfigurację certyfikatu; pozostaw null dla demonstracyjnego (z znakiem wodnym) podpisu
});
});
// System.Web odczytuje cały upload zanim Doconut go zobaczy: zachowaj maxRequestLength (KB) i
// maxAllowedContentLength (bytes) w Web.config powyżej MaxUploadMb widgetu.AddSignerWidget() bez argumentu włącza widget z ustawieniami domyślnymi. Nie przyznaje on samodzielnie możliwości podpisywania: potrzebuje AddPlugin<SignerPlugin>(), albo DoconutHost.Initialize zgłasza wyjątek:
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.Punkty końcowe i skrypt są obsługiwane przez handler oraz moduł zarejestrowany w 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>Moduł dostarcza skrypt niezależnie od tego, czy widget jest włączony. Bez AddSignerWidget() widget ładuje się i rysuje swoją strefę upuszczania, a pierwsze żądanie zwraca 404: widget następnie zgłasza Signing is not enabled on this server.
Limity przesyłania
ASP.NET odczytuje całe ciało żądania przed uruchomieniem DocImage.axd. Przesył powyżej MaxUploadMb, ale poniżej limitów hosta, otrzymuje własny JSON widgetu 413 (File is too large.). Przesył powyżej limitów hosta jest najpierw odrzucany przez IIS, z stroną błędu, której widget nie może odczytać. Utrzymuj oba limity hosta powyżej limitu widgetu:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Przesył wysłany bez Content-Length (chunked), który przekracza limity hosta, również otrzymuje stronę błędu IIS; nie ma obejścia tego przypadku.
Osadź to
Skrypt jest udostępniany pod adresem /doconut-res/js/doconutSigner.js. Jest to pojedynczy, samodzielny plik bez zależności. Wskaż basePath na obsługujący:
<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) przyjmuje selektor CSS lub element, rzuca wyjątek, jeśli montaż nie zostanie znaleziony, i zwraca uchwyt. Domyślny basePath widgetu, /doconut, to punkt końcowy ASP.NET Core; w tym pakiecie musi być '/DocImage.axd'.
Podpisujący przesyła plik PDF lub .docx, tworzy podpis (Rysuj na płótnie, Wpisz nazwę w czcionce podpisu lub Obraz z PNG, JPG lub GIF), przeciąga i zmienia jego rozmiar na stronie, a następnie podpisuje i pobiera wynik. Widget zawsze wysyła podpis jako PNG; przesłany obraz jest w przeglądarce konwertowany na PNG o wymiarach 520×160.
Opcje
| Opcja | Typ | Domyślnie | Uwagi |
|---|---|---|---|
basePath | string | '/doconut' | Gdzie serwowane są punkty końcowe ?sign= i obrazy podglądu. Ustaw '/DocImage.axd' w tym pakiecie |
resPath | string | '/doconut-res' | Zarezerwowane; widget zawiera własny CSS |
maxUploadMb | number | 25 | Tylko sprawdzanie po stronie klienta, więc zbyt duży plik odrzucany jest natychmiast. Limit po stronie serwera to MaxUploadMb w AddSignerWidget |
maxSignatureKb | number | 512 | Limit po stronie klienta dla trybu Obraz. Utrzymaj go równym limitowi serwera MaxSignatureImageKb |
previewWidth | number | 560 | Szerokość w pikselach podglądu strony |
licenseUrl | string | null | null | Zamienia powiadomienie o znakowaniu demo na link do tego URL |
signatureMode | string | 'certified' | Początkowy typ podpisu: 'certified' lub 'visual'. Każda inna wartość staje się 'certified' |
showSignatureModeToggle | boolean | true | Pokazuje wybór Podpis cyfrowy / Tylko wizualny. Z false, widget podpisuje się przy użyciu signatureMode |
wordOutput | string | 'pdf' | Początkowy format wyjścia dla źródeł .docx: 'pdf' lub 'docx'. Każda inna wartość staje się 'pdf' |
showOutputFormatToggle | boolean | true | Pokazuje wybór PDF / Word, tylko dla źródeł .docx. Z false, widget używa wordOutput |
labels | object | {} | Zastępuje dowolny podzbiór angielskich ciągów |
Ukrycie przełącznika nie wyłącza funkcji; ustawia wartość na stałe. Dwie typowe konfiguracje:
// Oba przełączniki wyświetlane, podpis cyfrowy domyślnie: pełny podpisujący samoobsługowy.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Tylko wizualny, bez przełącznika: prosty stempel bez oferowanego podpisu cyfrowego.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Wywołania zwrotne
| Wywołanie zwrotne | Wywoływane gdy | Dane |
|---|---|---|
onReady | Raz, przy montażu (nie ponownie przy reset()) | — |
onSourceLoaded | Plik jest otwierany i wyświetlany jest jego podgląd | { file: { token, name, pages, ext } } |
onSigned | Podpisywanie zakończyło się sukcesem | { downloadToken, downloadName, watermarked } |
onDownload | Przy każdym kliknięciu Pobierz | { downloadName, downloadToken } |
onError | Krok otwarcia, podpisywania lub pobierania nie powiódł się, lub plik w trybie Obraz jest za duży | { message } |
Wywołanie zwrotne, które rzuca wyjątek, jest przechwytywane i logowane; nigdy nie przerywa przepływu widgetu.
Imperatywny uchwyt
| Metoda | Zachowanie |
|---|---|
reset() | Powraca do ekranu upuszczania i czyści bieżący przepływ. Nie wywołuje ponownie onReady. Nie robi nic po destroy() |
loadFile(file) | Rozpoczyna przepływ z File. Nie robi nic, chyba że widget znajduje się na ekranie upuszczania; w razie potrzeby najpierw wywołaj reset() |
destroy() | Usuwa nasłuchiwacze, opróżnia montaż i zamraża instancję |
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());Etykiety
Każdy ciąg ma domyślną wartość w języku angielskim; labels nadpisuje dowolny podzbiór, a reszta pozostaje po angielsku. Fragmenty, które zmieniają się w czasie działania, używają {placeholders}, takie jak uploading: 'Uploading {name}…' i pages: '{n} pages'.
| Klucz | Domyślna wartość angielska |
|---|---|
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 |
Dalsze klucze obejmują krok umieszczania, ekran błędu, powiązaną formę powiadomienia demonstracyjnego (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) oraz ogłoszenia aria-live.
Gdy open lub run odpowiada 404 bez błędu JSON, widżet wyświetla signingNotEnabled. Błąd JSON z serwera zawsze ma pierwszeństwo, więc komunikaty takie jak wygasłe przesłanie pozostają widoczne.
Motywy
Widżet dodaje klasę dsw do swojego elementu montującego i odczytuje kolory, promień i czcionki z niestandardowych właściwości CSS, dzięki czemu możesz stylizować go bez modyfikowania jego wnętrza:
#host.dsw {
--dsw-accent: #b0522b; /* linki, focus, tryb aktywny */
--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; /* tryb Type */
}Domyślne: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, systemowa czcionka UI oraz kursywna czcionka podpisu.
Zbuduj własny front‑end
Widżet jest klientem tego kontraktu HTTP na DocImage.axd. Trasy odpowiadają 404, dopóki nie zostanie wywołane AddSignerWidget(). Błędy zawierają ciało JSON, { "error": "..." }, z wyjątkiem przypadków, gdy tabela podaje „tylko status”. Nieznana wartość ?sign= odpowiada 400.
| Ścieżka | Cel | Odpowiedź sukcesu |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | Prześlij PDF lub .docx i otwórz go w podglądzie | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Podpisz przesłany plik | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Strumieniuj podpisany plik | 200 — plik, Content-Disposition: attachment, Cache-Control: no-store |
ext w odpowiedzi open zawiera wiodącą kropkę (".docx"). Podgląd strony używa standardowej trasy obrazu przeglądarki, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; wyświetlana strona staje się placement.page.
Ciało 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"
}| Pole | Uwagi |
|---|---|
token | Token z open |
signature.kind | Drawn, Typed lub Image, bez rozróżniania wielkości liter; wszystko inne staje się Drawn. Tylko podpowiedź: ładunek jest zawsze PNG |
signature.payload | Czysty PNG w base64, bez prefiksu data:. Musi być prawdziwym PNG i po dekodowaniu nie większym niż MaxSignatureImageKb |
placement.page | liczony od 1 |
placement.x / y / w / h | Znormalizowane 0..1 od lewego górnego rogu, z x + w ≤ 1 i y + h ≤ 1 |
meta.signerName / reason / location | Opcjonalne. Każdy jest przycinany, pusty wartość jest odrzucana, a każdy jest ograniczany do 256 znaków |
wordOutput | pdf (domyślnie) lub docx; ignorowane dla źródeł PDF. Wszystko inne staje się pdf |
mode | certified (domyślnie) lub visual. Wszystko inne staje się certified |
downloadName następuje po wyjściu: <source>-signed.pdf lub <source>-signed.docx, a download wysyła pasujący Content-Type.
Przesłane źródło i podpisany wynik są przechowywane każdy przez 30 minut. Po tym, run i download odpowiadają 404 i plik musi zostać ponownie otwarty. Wszystkie tokeny są GUID‑ami.
| Ścieżka | Status | Kiedy | Ciało |
|---|---|---|---|
| any | 404 | Widżet nie jest włączony | status only |
| any | 405 | Nieprawidłowy czasownik (open i run potrzebują POST, download potrzebuje GET) | status only |
open | 400 | Nie jest przesyłaniem multipart | Expected a multipart file upload. |
open | 400 | Brak pliku lub pusty plik | No file uploaded. |
open | 400 | Wszystko inne niż .pdf lub .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Przesyłanie przekracza MaxUploadMb (ale nie limity IIS) | File is too large. |
run | 400 | Ciało nie jest prawidłowym JSON, lub jest puste | Malformed request. / Empty request. |
run | 400 | Token jest brakujący lub nie jest GUID | Invalid token. |
run | 404 | Przesyłanie wygasło lub nigdy nie zostało otwarte | Upload expired — please re-open the file. |
run | 400 | Brak podpisu lub brak umieszczenia | No signature supplied. / No placement supplied. |
run | 400 | Ładunek nie jest base64, jest pusty, za duży lub nie jest 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 | Umieszczenie jest poza stroną | The signature or its placement is invalid. |
run | 400 | Tryb certyfikowany, płatna licencja i brak certyfikatu | No signing certificate configured. |
run | 400 | Tryb certyfikowany z certyfikatem poza okresem ważności | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Przetwarzanie nie powiodło się | Zsanityzowana wiadomość |
download | 400 | Token jest brakujący lub nie jest GUID | status only |
download | 404 | Nieznany lub wygasły token | status only |
Pełny cykl z fetch:
// file: plik do podpisania; pngBase64: podpis jako czysty base64 PNG, bez prefiksu data:
// na przykład canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: prześlij plik
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: podpisz go
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: pobierz podpisany plik
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);
}Punkty końcowe są same-origin: ta wersja nie obsługuje CORS. Udostępnij swój interfejs UI i skrypt widgetu z tego samego pochodzenia co aplikacja, lub zastosuj reverse-proxy DocImage.axd i /doconut-res pod pochodzeniem swojego UI.
W produkcji
-
Zainstaluj wtyczkę obok pakietu core, w tej samej wersji:
Install-Package Doconut.NETFramework.Signer. -
Dodaj plik licencji. Umieść
Doconut.Viewer.Signer.licw tym samym folderze coDoconut.Viewer.lic. -
Uzyskaj swój certyfikat jako PFX wraz z kluczem prywatnym i łańcuchem wystawcy, od urzędu certyfikacji lub własnej PKI organizacji. Aby najpierw przetestować, użyj licencji demo (wbudowanego certyfikatu demo, z znakiem wodnym) lub samopodpisanego PFX.
-
Odczytaj certyfikat z konfiguracji, aby jego zmiana nigdy nie wymagała zmiany kodu:
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"] ?? "", }); });Trzymaj
.pfxwApp_Data, które IIS nigdy nie serwuje, i przechowuj hasło poza zwykłymWeb.config: użyj zaszyfrowanej sekcji konfiguracji lub magazynu tajemnic, z którego odczytuje Twoje wdrożenie. -
Podpisz dokument testowy w trybie Certified. Certyfikat, który jest wygasły lub jeszcze nie jest ważny, jest odrzucany z
The signing certificate expired on yyyy-MM-dd.(lubis not valid before), a czytnik PDF pokazuje, czy ufa podpisowi.
Zaufanie w czytnikach PDF. Czytnik wyświetla podpis jako ważny, gdy ufa korzeniowi certyfikatu. Przy PKI Twojej organizacji, obowiązuje to na każdym komputerze, który ufa Twojemu korzeniowi, co zazwyczaj oznacza wszystkie komputery w organizacji. Certyfikaty, które Adobe ufa na dowolnym komputerze (Adobe Approved Trust List), są – o ile wiemy – wydawane z kluczem prywatnym na tokenie sprzętowym lub HSM, czego ta wtyczka nie może używać: podpisuje wyłącznie z PFX. Potwierdź to u dostawcy certyfikatu, zanim będziesz polegać na takim zaufaniu.
Farmy serwerów
Widget przechowuje każde przesłanie i jego wynik w pamięci na serwerze, który obsłużył open. Za load balancerem bez sesji przyklejonych, późniejsze żądanie run, download lub podglądu może trafić na inny serwer i nie znaleźć przesłanego pliku. Zarejestruj współdzielony, zaszyfrowany magazyn widgetu poprzez drugi argument 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"; // folder, do którego każdy serwer może odczytywać i zapisywać
store.FarmKey = farmKey; // co najmniej 32 bajty, identyczne na każdym serwerze
// store.Ttl = TimeSpan.FromMinutes(30); // jak długo przechowywany jest przesył (domyślnie)
}));- Jeden serwer nie potrzebuje niczego: bez tego wywołania używany jest magazyn w pamięci.
- Przesyłane pliki i wyniki są szyfrowane w spoczynku na udziale (AES-256, encrypt-then-MAC), a każdy plik jest powiązany ze swoim tokenem, więc jeden token nigdy nie może odczytać pliku innego.
FarmKeymusi mieć co najmniej 32 bajty i być taki sam na każdym serwerze. Załaduj go z magazynu tajemnic; nigdy nie koduj na stałe. Rejestracja zgłaszaArgumentException, gdyRootPathjest brakujący lubFarmKeyjest krótszy niż 32 bajty.- Skieruj
RootPathna tę samą współdzieloną lokalizację, której używa rozproszony podgląd, i zapewnij każdemu serwerowi ten sam certyfikat podpisujący.
Odniesienie API
Fasada i opcje widżetu znajdują się w przestrzeni nazw Doconut; typy żądania i wyniku znajdują się w Doconut.Core.Models.Signing. SignerPlugin znajduje się w Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Rozwiązywany z DoconutHost.Services; konstruktor jest wewnętrzny. sourceExtension jest ".pdf" lub ".docx". Przy płatnej licencji używany jest cert i wynik jest czysty; przy licencji tymczasowej używany jest wbudowany certyfikat demonstracyjny, cert jest ignorowany, a wynik jest znakowany wodą.
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
}Jedna widoczna sygnatura umieszczona raz, plus opcjonalne metadane podpisującego.
VisibleSignature i SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes nie jest pusty
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes jest plikiem PNG dla każdego rodzaju. Rysowana lub wpisana sygnatura jest przezroczysta; przesłany obraz zachowuje swoją przezroczystość, więc nieprzezroczysty JPG pozostaje nieprzezroczysty. Kind jest jedynie wskazówką.
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 jest indeksowane od 1; X, Y, W i H są znormalizowane 0..1 od lewego górnego rogu.
SignatureMode i WordOutput
public enum SignatureMode { Certified, Visual } // Certified jest domyślny
public enum WordOutput { Pdf, Docx } // Pdf jest domyślny; ignorowane dla źródeł PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Podpisany dokument jako strumień z możliwością przeszukiwania oraz jego rozszerzenie z kropką (".pdf" lub ".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 nie jest pusty, lub PfxPath nie jest pusty
}Ustaw albo PfxBytes, albo PfxPath, plus Password. Ustawiające są tylko init: projekt wymaga C# 9.0 lub nowszego.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Ustawiane przez DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), który zwraca DoconutOptions, aby wywołania mogły być łańcuchowane. Null SigningCertificate oznacza certyfikat demonstracyjny przy licencji tymczasowej, a sygnatury wizualne tylko przy płatnej.
Rozwiązywanie problemów
| Objaw | Przyczyna | Rozwiązanie |
|---|---|---|
Każde żądanie zwraca pusty 500 po dodaniu wtyczki; dziennik zdarzeń pokazuje The Signer plugin is registered via AddPlugin but no active license grants Signer. | Brak licencji, plik TRIAL, licencja bez Signer lub płatna licencja poza swoim oknem wersji | Zainstaluj licencję, która przyznaje Signer, lub usuń AddPlugin<SignerPlugin>() |
Dziennik zdarzeń pokazuje AddSignerWidget() was called but the Signer plugin is not registered. | Widżet jest włączony bez swojej wtyczki | Dodaj options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
Dziennik zdarzeń pokazuje Doconut Signer: the certificate file was not found at '{path}'. | PfxPath wskazuje na brakujący plik | Napraw ścieżkę; wdroż plik w miejscu, gdzie konto puli aplikacji może go odczytać |
Dziennik zdarzeń pokazuje Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Nieprawidłowe hasło lub nie jest to plik PKCS#12 | Sprawdź hasło; użyj prawdziwego .pfx |
Dziennik zdarzeń pokazuje Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Plik PFX został wyeksportowany bez klucza prywatnego | Wyeksportuj go ponownie z kluczem prywatnym |
new SigningCertificate { … } nie kompiluje się | Projekt używa C# 7.3, które nie może ustawiać właściwości tylko init | Ustaw <LangVersion> na 9.0 lub nowszy |
Rozwiązywanie DocumentSigner rzuca No IDocumentSigner is registered. | SignerPlugin nie jest zarejestrowany | Dodaj AddPlugin<SignerPlugin>() w DoconutHost.Initialize |
| Wynik jest znakowany wodą | Licencja jest tymczasowa (Demo/NFR) | Użyj płatnej licencji, która przyznaje Signer |
run odpowiada 400 No signing certificate configured. | Płatna licencja, tryb Certified i brak certyfikatu | Skonfiguruj SigningCertificate, lub podpisz w trybie Visual |
run odpowiada 400 The signing certificate expired on yyyy-MM-dd. | Certyfikat jest nieaktualny | Zastąp go; sygnatury wizualne będą działać w międzyczasie |
Widżet ładuje się, ale wyświetla Signing is not enabled on this server. | AddSignerWidget() nie został wywołany, lub basePath nie jest '/DocImage.axd' | Wywołaj AddSignerWidget(); ustaw basePath: '/DocImage.axd' |
| Duże przesyłanie pokazuje stronę błędu IIS zamiast komunikatu widżetu | maxRequestLength / maxAllowedContentLength są poniżej MaxUploadMb | Podnieś oba limity hosta powyżej MaxUploadMb |
run odpowiada 400 The signature image must be a PNG., Signature image is not valid base64. lub Signature image is too large. | Niestandardowy interfejs UI wysłał URL data:, JPG lub więcej niż MaxSignatureImageKb | Wyślij czysty PNG w base64 w ramach limitu |
open odpowiada 413 File is too large. | Przesyłanie przekracza MaxUploadMb | Podnieś MaxUploadMb w AddSignerWidget; maxUploadMb widżetu jest tylko kontrolą po stronie klienta |
run lub download odpowiada 404 Upload expired — please re-open the file. | Okno 30 minut minęło, lub inny serwer w farmie nie ma przesłanego pliku | Otwórz plik ponownie; w farmie zarejestruj AddDoconutDistributedWidgets |
Podpisany .docx nie wyświetla podpisu w niektórych przeglądarkach | Wyjście Word zawiera podpis pakietu OOXML, który wiele przeglądarek nie pokazuje | Podpisz do PDF, domyślnie |
| Czytniki PDF mówią, że tożsamość podpisującego jest nieznana | Czytnik nie ufa głównemu certyfikatowi (certyfikat demonstracyjny nigdy nie jest zaufany) | Użyj certyfikatu z korzenia, któremu Twoi czytnicy ufają |
| Widżet nie działa, gdy UI znajduje się na innym pochodzeniu | Punkty końcowe nie mają obsługi CORS | Serwuj UI z tego samego pochodzenia, lub użyj reverse-proxy dla DocImage.axd i /doconut-res |
| Motyw nie jest stosowany | Selektor celuje w element wewnątrz montowania | Celuj w samo montowanie: #host.dsw lub #host |
Notatki o frameworku
W porównaniu z pakietami ASP.NET Core, ten pakiet różni się wyłącznie pod względem hostingu; API, kontrakt punktu końcowego, skrypt widgetu i zasady licencjonowania są takie same.
- Rejestracja znajduje się w
Application_Start, przezDoconutHost.Initialize, zamiastbuilder.Services.AddDoconut. Usługi takie jakAddDoconutDistributedWidgetstrafiają do jej drugiego argumentu. - Punkty końcowe są obsługiwane przez
DocImage.axd, a skrypt przezDoconutResourceModule, oba zarejestrowane wWeb.config, zamiastUseDoconut()iUseDoconutResources(). Widget wymagabasePath: '/DocImage.axd'. - Błędy uruchamiania pojawiają się jako pusty
500przy każdym żądaniu, a przyczyna jest zapisana w dzienniku zdarzeń Windows. - Przesyłanie plików jest w pełni odczytywane przez ASP.NET zanim Doconut je zobaczy, więc limity IIS muszą być powyżej
MaxUploadMb. - Brak linii logu uruchamiania dotyczącej certyfikatu: trzy błędy certyfikatu nadal są zgłaszane, ale linia podająca nazwę certyfikatu nie jest zapisywana.
- C# 9.0 lub nowszy jest wymagany, aby ustawić właściwości init-only
SigningCertificate. - Tylko Windows, tak jak reszta pakietu .NET Framework.
Czy ta strona była pomocna?