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 interfejsu front‑endowego.

Zainstaluj pakiet

Zainstaluj najnowszą stabilną wtyczkę Converter:

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Utrzymuj pakiet Converter w tej samej wersji co Doconut.NETStandard. Identyfikator pakietu to Doconut.NETStandard.Converter; .26.8.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.NETStandard.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 w przypadku brakującej licencji, starszego pliku TRIAL lub licencji nie‑tymczasowej, która nie przyznaje uprawnienia Converter — InvalidOperationException zgłaszany wewnątrz AddDoconut(), zanim aplikacja zacznie obsługiwać żądania. Akceptowane są tymczasowe rejestracje Demo/NFR; po ich wygaśnięciu konwersja pozostaje dostępna, ale z znakowanym wodą 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 pozycji 0, gotowy do natychmiastowego odczytu lub kopiowania. Pobierz DocumentConverter z DI w dowolnym miejscu, gdzie jest potrzebny — jest bezstanowy z założenia, więc pojedyncza instancja może być bezpiecznie używana wielokrotnie w różnych żądaniach.

viewer.Converter.GetConverter() nie istnieje w tym kontekście. Konwersja nie jest już dostępna przez instancję przeglądarki: wstrzyknij Doconut.DocumentConverter zamiast tego.

// 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 przyjmującym strumień 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

ConversionTarget (przestrzeń nazw Doconut.Configs.Conversion) ma 45 elementów:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Ten enum obejmuje wszystkie rodziny źródłowe. Poprzednia biblioteka posiadała typ *ConfigConverter dla każdej rodziny — WordConfigConverter, ExcelConfigConverter i tak dalej — każdy z własnym zagnieżdżonym enumem EnTargetFormat, oraz enum SourceFormatConverter dla wejścia. Wszystko to zostało usunięte; zobacz przewodnik migracji.

Nie każdy format źródłowy konwertuje się na każdy format docelowy — wtyczka mapuje rodzinę formatu źródłowego (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 enumu jako listy docelowej w interfejsie użytkownika: ?convert=open zwraca rzeczywiste allowedTargets dla 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 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 wywołania AddConverterWidget(), trzy endpointy ?convert= zwracają 404 — ale sam plik JS jest nadal udostępniany (jest 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 aby istniała licencja uprawniająca do 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();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

Zbuduj własny interfejs

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

Przesłane bajty źródłowe są przechowywane po stronie serwera z 30‑minutowym TTL; po upływie tego czasu run zwraca 404 i plik musi zostać ponownie otwarty. Wynik konwersji pozostaje w tym samym magazynie — downloadToken otrzymuje własne, świeże 30‑minutowe okno po zakończeniu konwersji — natomiast 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 magazynu.

sourceExt w odpowiedzi open nie zawiera wiodącej kropki (np. "docx") — jest to odwrotna konwencja w stosunku do parametru sourceExtension w metodzie 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 pobierana z wstrzykiwania zależności; nie twórz ani nie zwalniaj tej usługi ręcznie.

Dla widgetu internetowego, tymczasowe przechowywanie przesyłania i pobierania ma niezależne 30‑minutowe czasy życia (TTL). Token resultToken widza podąża za okresem życia sesji widza. Zamknięcie wyniku widza nie usuwa nadal ważnego tymczasowego przechowywania pobrania, 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ę 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ę jedynie bajty wyjściowe.