Μετατροπή Εγγράφων στην Πλευρά του Διακομιστή σε .NET με Doconut

Introduction

Η μετατροπή εγγράφων στην πλευρά του διακομιστή επιτρέπει σε μια εφαρμογή να δημιουργεί ένα κανονικοποιημένο αποτέλεσμα χωρίς να αυτοματοποιεί το Microsoft Office ή να στέλνει την πηγή σε ξεχωριστή διαδικτυακή υπηρεσία μετατροπής. Αυτό μπορεί να απλοποιήσει τις πύλες εγγράφων, τις εργασίες παρασκηνίου και τις ελεγχόμενες ροές εξαγωγής—αλλά η εφαρμογή φιλοξενίας εξακολουθεί να διαχειρίζεται τον έλεγχο πρόσβασης, την αποθήκευση, τη διατήρηση, την παρακολούθηση και την παράδοση του αποτελέσματος.

Το .NET 8 Converter Plugin της Doconut εκθέτει τη μετατροπή μέσω της υπηρεσίας DocumentConverter που ενσωματώνεται με εξάρτηση. Αυτός ο οδηγός εστιάζει στην τρέχουσα καταχώριση και το μοντέλο API και αποφεύγει τη σύνδεση της μετατροπής με μια συνεδρία προβολέα.

---

Install matching packages

Εγκαταστήστε τα βασικά πακέτα προβολέα και μετατροπέα:

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

Διατηρήστε και τα δύο πακέτα στην ίδια έκδοση κυκλοφορίας. Όταν η αναπαραγωγιμότητα των builds είναι σημαντική, κλειδώστε την έκδοση στο αρχείο έργου ή περάστε την ίδια τιμή --version και στις δύο εντολές.

Register the Converter Plugin

Τα πρόσθετα καταχωρούνται μέσα στην κλήση επιστροφής επιλογών AddDoconut. Δεν υπάρχει ξεχωριστή μέθοδος καταχώρισης AddConverter():

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

Η εφαρμογή πρέπει να χρησιμοποιεί μια άδεια που παρέχει τη δυνατότητα Converter. Επιλύστε τα σφάλματα εκκίνησης και αδειοδότησης πριν αποδεχτείτε εργασίες μετατροπής· μην τα αναβάλλετε σε μια ουρά παρασκηνίου όπου γίνονται πιο δύσκολα στην διάγνωση.

Convert a file from C#

Ενσωματώστε το DocumentConverter στο σημείο λήψης ή στην υπηρεσία που διαχειρίζεται το αίτημα μετατροπής. Ο κατασκευαστής του μετατροπέα είναι εσωτερικός, επομένως ο κώδικας της εφαρμογής δεν πρέπει να τον δημιουργεί άμεσα.

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");
});

Η επιστρεφόμενη ροή είναι αναζητήσιμη και βρίσκεται στην αρχή. Ο καλούντας την κατέχει και πρέπει να την απελευθερώσει μετά την αντιγραφή ή την επιστροφή του περιεχομένου.

Convert an uploaded stream

Η υπερφόρτωση ροής απαιτεί την επέκταση του αρχείου προέλευσης—συμπεριλαμβανομένου του αρχικού σημείου—επειδή ο μετατροπέας τη χρησιμοποιεί για την ανίχνευση της μορφής προέλευσης:

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");
});

Αντιμετωπίστε το όνομα αρχείου και την επέκταση ως μη αξιόπιστη είσοδο. Εφαρμόστε όρια ανεβάσματος, επικυρώστε τον τύπο προέλευσης, εξουσιοδοτήστε τον χρήστη που κάνει το αίτημα και αποφύγετε τη χρήση του υποβληθέντος ονόματος αρχείου ως διαδρομή αποθήκευσης.

Choose targets from actual capabilities

Το πρόσθετο εκθέτει ένα enum ConversionTarget, αλλά δεν μπορεί κάθε μορφή προέλευσης να παραγάγει κάθε στόχο. Μια προσαρμοσμένη διεπαφή χρήστη πρέπει να εμφανίζει μόνο τους στόχους που επιτρέπονται για την ανεβασμένη προέλευση αντί να εμφανίζει κάθε τιμή του enum.

Κατά τη χρήση του προαιρετικού widget μετατροπής της Doconut, η ανοιχτή απάντησή του περιλαμβάνει το allowedTargets. Χρησιμοποιήστε αυτήν την απάντηση ως πηγή αλήθειας για το τρέχον αρχείο.

Design background conversion as an application workflow

Ο μετατροπέας μπορεί να κληθεί από μια υπηρεσία εφαρμογής ή από έναν εργαζόμενο σε ουρά. Μια αξιόπιστη εργασία συνήθως περιλαμβάνει:

1. Ένα αυθεντικοποιημένο αίτημα που καταγράφει την προέλευση και τον επιθυμητό στόχο.
2. Ένα μήνυμα ουράς που περιέχει το αναγνωριστικό εργασίας της εφαρμογής, όχι ακατέργαστα διαπιστευτήρια.
3. Έναν εργαζόμενο που ανακτά την προέλευση μέσω εξουσιοδοτημένης αφαίρεσης αποθήκευσης.
4. Μια περιορισμένη λειτουργία μετατροπής με δυνατότητα ακύρωσης.
5. Ανθεκτική αποθήκευση εξόδου με σαφείς κανόνες διατήρησης.
6. Μια ενημέρωση κατάστασης που δεν αποκαλύπτει εσωτερικές διαδρομές ή ευαίσθητες λεπτομέρειες εξαιρέσεων.

Μετρήστε τη σύγκλιση με αντιπροσωπευτικά έγγραφα πριν επιλέξετε τον αριθμό των εργαζομένων. Το κόστος μετατροπής διαφέρει ανάλογα με τη μορφή προέλευσης, την πολυπλοκότητα του εγγράφου, τις γραμματοσειρές, τις εικόνες και τον στόχο εξόδου.

Keep security claims precise

Η εκτέλεση του μετατροπέα μέσα στην .NET εφαρμογή σας σημαίνει ότι η λειτουργία μετατροπής δεν απαιτεί αυτοματοποίηση του Microsoft Office ή ξεχωριστό διαδικτυακό API μετατροπής. Δεν εγγυάται αυτόματα την ιδιωτικότητα, τη συμμόρφωση, τη διαγραφή ή την κρυπτογράφηση για ολόκληρο το σύστημα.

Αυτά τα χαρακτηριστικά εξαρτώνται από το πώς η εφαρμογή αυθεντικοποιεί τους χρήστες, ανακτά τα αρχεία προέλευσης, διαμορφώνει την αποθήκευση, προστατεύει τα αρχεία καταγραφής, διανέμει την έξοδο και αφαιρεί τα προσωρινά ή διατηρημένα δεδομένα.

Operational checklist

• Διατηρήστε τις εκδόσεις των Doconut.NET8 και Doconut.NET8.Converter ευθυγραμμισμένες.
• Καταχωρίστε το ConverterPlugin κατά τη διαμόρφωση της υπηρεσίας.
• Αντιμετωπίστε το DocumentConverter μέσω ενσωμάτωσης εξαρτήσεων.
• Συμπεριλάβετε το αρχικό σημείο στις επεκτάσεις πηγής ροής.
• Απελευθερώστε τις ροές προέλευσης και αποτελέσματος.
• Χρησιμοποιήστε ακύρωση και όρια μεγέθους αρχείου σε επίπεδο εφαρμογής.
• Επικυρώστε την υποστήριξη προέλευσης-προς-στόχο αντί να υποθέτετε ότι κάθε ζεύγος λειτουργεί.
• Δοκιμάστε την πιστότητα και τη χρήση πόρων με αντιπροσωπευτικά αρχεία.
• Διατηρήστε τις αποφάσεις αποθήκευσης, εξουσιοδότησης, ελέγχου και διατήρησης στον κώδικα της εφαρμογής.

Δείτε την επίσημη Plugin Μετατροπέα Doconut επισκόπηση και την Τεκμηρίωση Doconut για τρέχουσες πληροφορίες προϊόντος και ενσωμάτωσης.