Wtyczka Konwertera

Wtyczka Converter przekształca Doconut w usługę konwersji dokumentów. Dostarcza silnik stojący za publiczną fasadą DocumentConverter oraz — opcjonalnie — 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.NET8.Converter

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

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

Utrzymuj pakiet Converter w tej samej wersji co Doconut.NET8. Identyfikator pakietu to Doconut.NET8.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.NET8.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 uruchomieniu w przypadku brakującej licencji, starszego pliku TRIAL lub licencji nie‑tymczasowej, która nie przyznaje możliwości Converter — InvalidOperationException podniesiony wewnątrz AddDoconut(), przed obsługą żądań przez aplikację. Tymczasowe rejestracje Demo/NFR są akceptowane; po ich wygaśnięciu kalendarzowym konwersja pozostaje dostępna z oznaczoną znakiem wodnym wyjściem. 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 odczytu lub kopiowania od razu. Rozwiąż DocumentConverter z DI, gdziekolwiek go potrzebujesz — jest bezstanowy z założenia, więc pojedyncza instancja może być bezpiecznie używana w wielu żą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 chroniony.
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 się na każdy docelowy — wtyczka mapuje rodzinę formatów źródłowych (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) na własny stały zestaw dozwolonych celów. Nie koduj na sztywno 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 typu Drop‑in

Endpointy ?convert=open|run|download widżetu są opcjonalne i domyślnie wyłączone — zabezpieczone domyślnie. 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 niezależnie (jest 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.

Dostosowanie widżetu

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; no-op, chyba że aktualnie idle
conv.destroy();       // usuwa nasłuchiwacze, opróżnia mount; instancja jest nieużywalna po tym

Zbuduj własny frontend

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

Przesłane bajty źródła są przechowywane po stronie serwera z 30‑minutowym TTL; po upływie tego okna, run zwraca 404 i plik musi być ponownie otwarty. Skonwertowany wynik znajduje się 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 przeglądarki, którego czas życia podąża za pamięcią podręczną sesji przeglądarki, 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 przeszukiwalny 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 należy ręcznie tworzyć ani zwalniać tej usługi.

W przypadku widgetu internetowego, schowki przesyłania i pobierania mają niezależne 30‑minutowe czasy życia (TTL). Viewer resultToken podąża za okresem życia sesji podglądu. Zamknięcie wyniku podglądu nie usuwa nadal ważnego schowka pobierania, a zresetowanie widgetu 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ę na podstawie tej samej reguły: fasada C# DocumentConverter wyprowadza ją wewnętrznie z stanu IsViewerLicensed i IsTemporary licencji, a obsługa ?convert=run widgetu 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.