Wtyczka Konwertera

Wtyczka Converter przekształca Doconut w usługę konwersji dokumentów. Dostarcza silnik stojący za publiczną fasadą DocumentConverter oraz — po włączeniu — 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, podaj 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 nazwie pobranego 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 osobnym pakiecie NuGet, Doconut.NET8.Converter, zainstalowanym razem z podstawowym pakietem 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, jeśli brakuje licencji, istnieje starszy plik TRIAL lub licencja nie‑tymczasowa, która nie przyznaje możliwości Converter — InvalidOperationException podnoszone wewnątrz AddDoconut(), przed obsługą żądań przez aplikację. Tymczasowe rejestracje Demo/NFR są akceptowane; po upływie ich terminu konwersja pozostaje dostępna z oznaczeniem wodnym. Nie ma cichego darmowego poziomu. Zobacz License Setup, aby dowiedzieć się, jak ładowane są licencje.

Konwertuj z C#

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

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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ć wiodącą kropkę (".xlsx", a 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 format źródłowy konwertuje się na każdy format 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 sztywno tego wyliczenia jako listy docelowej w UI: ?convert=open zwraca rzeczywiste allowedTargets dla właśnie przesłanego pliku i to powinno sterować wyborem.

Gotowy widget

Endpointy widgetu ?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 sam plik JS jest nadal udostępniany (to zwykły wbudowany zasób statyczny; tylko endpointy, z którymi się komunikuje, są zabezpieczone). AddConverterWidget() nadal wymaga, aby wtyczka Converter była zarejestrowana oraz licencji przyznającej Converter — nie przyznaje ona samodzielnie praw do konwersji.

Dostosuj widget

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

Wywołania zwrotne:

Doconut.convert() zwraca samą instancję widgetu — zachowaj ją, aby sterować widgetem programowo:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // powrót do ekranu bezczynności/upuszczania; nie wywołuje ponownie onReady
conv.loadFile(file);  // rozpoczyna przepływ z obiektem File; nie robi nic, jeśli nie jest w stanie bezczynności
conv.destroy();       // usuwa nasłuchiwacze, opróżnia montaż; po tym instancja jest nieużyteczna

Zbuduj własny frontend

Widget jest jedynie klientem tego kontraktu HTTP — zbuduj własny frontend bezpośrednio przeciwko niemu, aby uzyskać inne UX. Wszystkie trzy trasy znajdują się pod gałęzią ASP.NET, w której zamontowano UseDoconut() (zwykle /doconut):

Przesłane bajty źródła są przechowywane po stronie serwera z TTL 30 minut; po upływie tego okna run zwraca 404 i plik musi być ponownie otwarty. Wynik konwersji pozostaje w tym samym magazynie — 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 magazynu.

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 twórz ani nie zwalniaj usługi ręcznie.

Dla widgetu internetowego, magazyny upload i download mają niezależne TTL 30 minut. resultToken przeglądarki podąża za czasem życia sesji przeglądarki. Zamknięcie wyniku przeglądarki nie usuwa nadal ważnego magazynu pobrania, a resetowanie widgetu w przeglądarce 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 ze stanu licencji IsViewerLicensed i IsTemporary, a obsługa widgetu ?convert=run 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.