Konwersja dokumentów po stronie serwera w .NET z Doconut

Wprowadzenie

Konwersja dokumentów po stronie serwera pozwala aplikacji generować ustandaryzowany wynik bez automatyzacji Microsoft Office ani wysyłania źródła do oddzielnej usługi konwersji online. To może uprościć portale dokumentacyjne, zadania w tle oraz kontrolowane przepływy eksportu — ale aplikacja‑gospodarz nadal kontroluje dostęp, przechowywanie, retencję, monitorowanie i dostarczanie wyniku.

Wtyczka konwertera .NET 8 firmy Doconut udostępnia konwersję poprzez wstrzykiwaną zależność DocumentConverter. Ten przewodnik skupia się na aktualnym modelu rejestracji i API oraz unika powiązania konwersji z sesją podglądu.

---

Zainstaluj pasujące pakiety

Zainstaluj podstawowe pakiety podglądu i konwertera:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Utrzymuj oba pakiety w tej samej wersji wydania. Gdy istotne są odtwarzalne kompilacje, przypnij wersję w pliku projektu lub przekaż tę samą wartość --version do obu poleceń.

Zarejestruj wtyczkę konwertera

Wtyczki rejestruje się wewnątrz wywołania zwrotnego opcji AddDoconut. Nie istnieje osobna metoda rejestracji AddConverter():

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

Aplikacja musi używać licencji, która przyznaje możliwość konwersji. Rozwiąż problemy z uruchamianiem i licencjonowaniem, zanim przyjmiesz zadania konwersji; nie odkładaj ich na kolejkę w tle, gdzie trudniej je zdiagnozować.

Konwertuj plik z C#

Wstrzyknij DocumentConverter do punktu końcowego lub usługi, która obsługuje żądanie konwersji. Konstruktor konwertera jest wewnętrzny, więc kod aplikacji nie powinien go tworzyć bezpośrednio.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Zwrócony strumień jest przeszukiwalny i ustawiony na początek. Wywołujący jest jego właścicielem i powinien go zwolnić po skopiowaniu lub zwróceniu zawartości.

Konwertuj przesłany strumień

Przeciążenie strumieniowe wymaga podania rozszerzenia źródła — łącznie z początkową kropką — ponieważ konwerter używa go do określenia formatu źródłowego:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Traktuj nazwę pliku i rozszerzenie jako niepewne dane wejściowe. Wymuszaj limity przesyłania, waliduj typ źródła, autoryzuj użytkownika i unikaj używania przesłanej nazwy pliku jako ścieżki przechowywania.

Wybierz cele zgodnie z rzeczywistymi możliwościami

Wtyczka udostępnia wyliczenie ConversionTarget, ale nie każdy format źródłowy może wygenerować każdy cel. Interfejs użytkownika powinien wyświetlać tylko cele dopuszczone dla przesłanego źródła, a nie wszystkie wartości wyliczenia.

Kiedy używasz opcjonalnego widżetu konwertera Doconut, jego otwarta odpowiedź zawiera allowedTargets. Użyj tej odpowiedzi jako jedynego źródła prawdy dla bieżącego pliku.

Zaprojektuj konwersję w tle jako przepływ pracy aplikacji

Konwerter może być wywoływany z usługi aplikacji lub z kolejki pracownika. Solidne zadanie zazwyczaj obejmuje:

1. Uwierzytelnione żądanie, które rejestruje źródło i żądany cel.
2. Wiadomość kolejki zawierająca identyfikator zadania aplikacji, a nie surowe poświadczenia.
3. Pracownika, który pobiera źródło poprzez autoryzowaną abstrakcję przechowywania.
4. Ograniczoną operację konwersji z możliwością anulowania.
5. Trwałe przechowywanie wyniku z wyraźnymi zasadami retencji.
6. Aktualizację statusu, która nie ujawnia wewnętrznych ścieżek ani wrażliwych szczegółów wyjątków.

Mierz współbieżność przy użyciu reprezentatywnych dokumentów, zanim zdecydujesz o liczbie pracowników. Koszt konwersji zależy od formatu źródłowego, złożoności dokumentu, czcionek, obrazów i docelowego formatu wyjściowego.

Zachowaj precyzyjne roszczenia bezpieczeństwa

Uruchomienie konwertera wewnątrz aplikacji .NET oznacza, że operacja konwersji nie wymaga automatyzacji Microsoft Office ani oddzielnego interfejsu API konwersji online. Nie zapewnia to automatycznie prywatności, zgodności, usuwania ani szyfrowania całego systemu.

Te właściwości zależą od tego, jak aplikacja uwierzytelnia użytkowników, pobiera pliki źródłowe, konfiguruje przechowywanie, chroni logi, dystrybuuje wyniki i usuwa tymczasowe lub zachowane dane.

Lista kontrolna operacyjna

• Utrzymuj wersje Doconut.NET8 i Doconut.NET8.Converter zgodne.
• Zarejestruj ConverterPlugin podczas konfiguracji usług.
• Uzyskaj DocumentConverter poprzez wstrzykiwanie zależności.
• Dołączaj początkową kropkę w rozszerzeniach źródeł strumieniowych.
• Zwolnij strumienie źródłowe i wynikowe.
• Używaj anulowania i limitów rozmiaru plików na poziomie aplikacji.
• Waliduj wsparcie źródło‑cel zamiast zakładać, że każda para działa.
• Testuj wierność i zużycie zasobów przy użyciu reprezentatywnych plików.
• Trzymaj decyzje dotyczące przechowywania, autoryzacji, audytu i retencji w kodzie aplikacji.

Zobacz oficjalny przegląd Wtyczki konwertera Doconut oraz dokumentację Doconut w celu uzyskania aktualnych informacji o produkcie i integracji.