Wtyczka Konwertera

Wtyczka Converter przekształca Doconut w usługę konwersji dokumentów. Dostarcza silnik stojący za publiczną fasadą DocumentConverter oraz — po wyrażeniu zgody — gotowy widget z własnym kontraktem HTTP, dzięki czemu możesz konwertować dokumenty z C#, z widgetu lub z własnego frontendu.

Zainstaluj pakiet

Zainstaluj najnowszą stabilną wtyczkę Converter:

dotnet add package Doconut.NET6.Converter

Aby przypiąć wtyczkę do bieżącej wersji 26.7.0, podaj wersję osobno:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Utrzymuj pakiet Converter w tej samej wersji co Doconut.NET6. Identyfikator pakietu to Doconut.NET6.Converter; .26.7.0 pojawia się tylko w pobranej nazwie pliku .nupkg.

Zarejestruj wtyczkę

Nie ma metody AddConverter() — model wtyczek Doconut jest jednolity. Każda wtyczka, w tym Converter, rejestruje się w ten sam sposób: wywołaj AddPlugin<TPlugin>() wewnątrz AddDoconut(). ConverterPlugin jest dostarczany w własnym pakiecie NuGet, Doconut.NET6.Converter, zainstalowany obok podstawowego pakietu przeglądarki.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

To wywołanie rzuca wyjątek przy uruchamianiu w przypadku brakującej licencji, przestarzałego pliku TRIAL lub licencji nie‑tymczasowej, która nie przyznaje możliwości Converter — InvalidOperationException podniesiony wewnątrz AddDoconut(), zanim aplikacja zacznie obsługiwać żądania. Tymczasowe rejestracje Demo/NFR są akceptowane; po ich wygaśnięciu konwersja pozostaje dostępna z wodnym znakiem w wyjściu. Nie ma cichego darmowego poziomu. Zobacz Konfiguracja licencji aby dowiedzieć się, jak ładowane są licencje.

Konwertuj z C#

Każda konwersja zwraca przeszukiwalny MemoryStream ustawiony na 0, gotowy do natychmiastowego odczytu lub kopiowania. Rozwiąż DocumentConverter z DI, gdziekolwiek go potrzebujesz — jest bezstanowy z założenia, więc pojedyncza instancja może być bezpiecznie używana wielokrotnie w żądaniach.

// Wstrzyknij DocumentConverter; jego konstruktor jest wewnętrzny, więc nigdy nie `new` go.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension zawiera wiodącą kropkę. password jest null, chyba że dokument jest zabezpieczony.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dwa szczegóły, które łatwo pomylić: sourceExtension w przeciążeniu strumienia musi zawierać początkową kropkę (".xlsx", nie "xlsx") — konwerter dopasowuje ją do katalogu formatów i sama rozszerzenie nie zostanie rozpoznane. I pomimo nazwy, WordToHtmlAsync zwraca Task<Stream>, a nie Task<string> — otrzymujesz dokument HTML (obrazy osadzone jako Base64) jako strumień, tak jak każdy inny wynik konwersji.

Formaty docelowe

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Nie każdy źródłowy format konwertuje na każdy docelowy — wtyczka mapuje rodzinę formatów źródłowych (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, dokument internetowy) na własny stały zestaw dozwolonych celów. Nie koduj na stałe tego wyliczenia jako listy docelowej w UI: ?convert=open zwraca rzeczywisty allowedTargets dla dowolnego właśnie przesłanego pliku i to powinno sterować wyborem.

Widżet Drop-in

Endpointy widżetu ?convert=open|run|download są opcjonalne i domyślnie wyłączone — zabezpieczone z góry. Włącz je po stronie serwera, razem z rejestracją wtyczki:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Bez AddConverterWidget(), trzy endpointy ?convert= zwracają 404 — ale plik JS jest nadal udostępniany (to zwykły osadzony zasób statyczny; tylko endpointy, z którymi się komunikuje, są zabezpieczone). AddConverterWidget() nadal wymaga zarejestrowania wtyczki Converter oraz licencji, która przyznaje Converter — nie przyznaje ona samodzielnie praw do konwersji.

Dostosuj widżet

Opcje inicjalizacji przekazywane do Doconut.convert(selector, options):

Wywołania zwrotne:

Doconut.convert() zwraca samą instancję widżetu — zachowaj ją, aby sterować widżetem programowo:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // powrót do ekranu idle/drop; nie wywołuje ponownie onReady
conv.loadFile(file);  // rozpoczyna przepływ z obiektem File; nie wykonuje operacji, chyba że aktualnie idle
conv.destroy();       // usuwa nasłuchiwacze, opróżnia mount; instancja jest nieużyteczna po tym

Zbuduj własny interfejs

Widżet jest jedynie klientem tego kontraktu HTTP — zbuduj własny interfejs bezpośrednio na jego bazie, aby uzyskać inny UX. Wszystkie trzy trasy znajdują się pod gałęzią ASP.NET, w której zamontowany jest UseDoconut() (zwykle /doconut):

Przesłane bajty źródła są przechowywane po stronie serwera z TTL 30 minut; po upływie tego okna run odpowiada 404 i plik musi zostać ponownie otwarty. Wynik konwersji pozostaje w tym samym schowku — downloadToken otrzymuje własne, świeże 30‑minutowe okno po zakończeniu konwersji — podczas gdy resultToken jest zwykłym tokenem sesji podglądu, którego czas życia podąża za pamięcią podręczną sesji podglądu, niezależnie od schowka.

sourceExt w odpowiedzi open nie ma wiodącej kropki (np. "docx") — odwrotna konwencja w stosunku do parametru sourceExtension w DocumentConverter.ConvertAsync, który wymaga kropki.

Tryby awarii, pogrupowane według trasy:

Własność zasobów

Konwerter zwraca przewijalny MemoryStream ustawiony na zero. Wywołujący jest właścicielem tego strumienia i powinien go zwolnić po skopiowaniu lub zwróceniu jego zawartości. Usługa DocumentConverter jest bezstanowa i jest rozwiązywana z wstrzykiwania zależności; nie twórz ani nie zwalniaj usługi ręcznie.

Dla widżetu internetowego, tymczasowe przechowywanie przesyłania i pobierania ma niezależne 30‑minutowe czasy życia (TTL). Widok resultToken podąża zamiast tego za okresem życia sesji widoku. Zamknięcie wyniku widoku nie usuwa nadal ważnego tymczasowego przechowywania pobrania, a zresetowanie widżetu przeglądarki nie wydłuża żadnego z TTL.

Rozwiązywanie problemów

Dodawanie znaków wodnych

Po zarejestrowaniu ConverterPlugin, licencja hosta znajduje się w jednym z trzech stanów:

Obie ścieżki wywołań obliczają flagę według tej samej reguły: fasada C# DocumentConverter wyprowadza ją wewnętrznie z IsViewerLicensed i stanu IsTemporary licencji, a obsługa ?convert=run widżetu wykonuje równoważne sprawdzenie (IsViewerLicensed && !IsTrial && !IsTemporary), aby wypełnić pole watermarked, które zwraca. Integrację można zbudować i przetestować end‑to‑end na licencji ewaluacyjnej przed zakupem — zmieniają się tylko bajty wyjściowe.