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 hostująca nadal zarządza kontrolą dostępu, przechowywaniem, retencją, monitorowaniem i dostarczaniem wyniku.

Wtyczka .NET 8 Converter firmy Doconut udostępnia konwersję poprzez wstrzykiwaną zależność DocumentConverter. Ten przewodnik koncentruje 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.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Aplikacja musi używać licencji, która przyznaje uprawnienie do konwertera. Rozwiąż problemy z uruchamianiem i licencjonowaniem przed przyjęciem zadań konwersji; nie odkładaj ich na kolejkę w tle, gdzie stają się trudniejsze do diagnozy.

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 niezweryfikowane dane wejściowe. Wymuszaj limity przesyłania, waliduj typ źródła, autoryzuj użytkownika żądającego i unikaj używania przesłanej nazwy pliku jako ścieżki przechowywania.

Wybieraj 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ć jedynie cele dopuszczone dla przesłanego źródła, a nie wszystkie wartości wyliczenia.

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

Projektuj 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 przed określeniem liczby pracowników. Koszt konwersji różni się w zależności 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.

Właściwości te 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.
• Rozwiązuj 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 Doconut Converter Plugin oraz dokumentację Doconut w celu uzyskania aktualnych informacji o produkcie i integracji.