Οδηγός: Άνοιγμα Εγγράφων με τον Ενσωματωμένο Doconut Viewer σε .NET 8

Εισαγωγή

Παλιότερα παραδείγματα Doconut μπορεί να δημιουργούν το Viewer απευθείας με ορίσματα cache, HTTP-context και license-path. Αυτό δεν είναι το τρέχον μοντέλο ενσωμάτωσης .NET 8. Η AddDoconut() καταχωρίζει το Viewer με dependency injection, και τα σημεία λήψης της εφαρμογής λαμβάνουν την υπηρεσία αντί να καλούν κατασκευαστή.

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

---

1. Εγκατάσταση και καταχώριση Doconut

Προσθέστε το πακέτο .NET 8:

dotnet add package Doconut.NET8

Καταχωρίστε το Doconut και τις υπηρεσίες συνεδρίας ASP.NET:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Συνδέστε το middleware με τη απαιτούμενη σειρά. Το middleware πόρων πρέπει να εκτελείται πριν από το τελικό middleware εγγράφου:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath συντονίζει τη διαμόρφωση αλλά δεν δημιουργεί το κλάδο ASP.NET από μόνο του. Η αντιστοιχισμένη διαδρομή /doconut πρέπει να ταιριάζει με το BasePath του widget.

2. Προσθήκη της επιφάνειας προβολέα και των πόρων

Ο προβολέας προγράμματος περιήγησης Doconut είναι ένα plugin jQuery. Σε μια σελίδα Razor, ενσωματώστε το Viewer και ζητήστε του να εκδώσει τις ετικέτες πόρων με τη σειρά εξαρτήσεων:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Αρχικοποιήστε το widget με διαδρομές που ταιριάζουν με την καταχώριση του διακομιστή:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Η κεφαλοποίηση των επιλογών είναι σημαντική. Χρησιμοποιήστε τα ονόματα που εμφανίζει η εγκατεστημένη έκδοση αντί να τα ομαλοποιείτε σε ένα ενιαίο στυλ.

3. Ενσωμάτωση Viewer και άνοιγμα εγγράφου

Viewer καταχωρείται ως transient υπηρεσία. Λάβετε το μέσω ενσωμάτωσης σε σημείο λήψης, ενσωμάτωσης κατασκευαστή ή της ισοδύναμης δυνατότητας στην εφαρμογή ASP.NET Core.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

Για μεταφόρτωση, παρέχετε ένα stream και ένα FileInfo του οποίου η επέκταση προσδιορίζει τη μορφή προέλευσης:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

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

4. Μετάδοση του διακριτικού στο widget

Ανακτήστε το endpoint ανοίγματος και παραδώστε το επιστρεφόμενο διακριτικό στο objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Θεωρήστε το διακριτικό ως διαπιστευτήριο φορέα για μια ζωντανή συνεδρία εγγράφου:

• Μην το καταγράφετε ή το αποθηκεύετε.
• Επιστρέψτε το μόνο σε εξουσιοδοτημένο πελάτη.
• Μην εκθέτετε τη διαδρομή του αρχικού αρχείου.
• Ξανανοίξτε το έγγραφο όταν λήξει η συνεδρία.
• Κλείστε τη συνεδρία όταν το έγγραφο δεν χρειάζεται πλέον.

5. Εσκεμμένο κλείσιμο των συνεδριών στο διακομιστή

Ο κώδικας πελάτη μπορεί να καλέσει objViewer.Close() όταν ο χρήστης αφήνει τον προβολέα. Οι ροές εργασίας του διακομιστή μπορούν επίσης να ανακαλέσουν ρητά ένα γνωστό διακριτικό:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

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

6. Προσθήκη προαιρετικών μονάδων μόνο μετά την επιτυχή λειτουργία του πυρήνα

Η αναζήτηση και οι σημειώσεις προσδένονται στον ίδιο αρχικοποιημένο προβολέα. Προσθέστε τα CSS, τα scripts, τα mounts, τους ελέγχους αδειοδότησης και τις κλήσεις ζωής μόνο μετά την επιτυχή ολοκλήρωση της βασικής ροής:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Αυτή η σειρά διαχωρίζει τις αποτυχίες του πυρήνα από τη διαμόρφωση προαιρετικών μονάδων.

Συνήθη σφάλματα μετάβασης

Παλιό ή λανθασμένο πρότυπο	Τρέχουσα κατεύθυνση .NET 8
new Viewer(cache, accessor, licensePath)	Ενσωματώστε το Viewer μετά το AddDoconut()
Στατικές κλήσεις φόρτωσης άδειας στον κώδικα αιτήματος	Διαμορφώστε την είσοδο άδειας στο AddDoconut()
Συγχρονικά παραδείγματα OpenDocument(...)	Χρησιμοποιήστε OpenDocumentAsync(...)
Ένα εξωτερικό ή εφεύρετο CDN προβολέα	Εκδώστε ενσωματωμένους πόρους με ReferenceCss και ReferenceScripts
Γενικό API JavaScript init()	Αρχικοποιήστε $('#div_ctlDoc').docViewer(...)
Διατήρηση του διακριτικού του προβολέα	Διατηρήστε το ID του εγγράφου σας· θεωρήστε το διακριτικό ως προσωρινό

Χρησιμοποιήστε την επίσημη Τεκμηρίωση Doconut και επαληθεύστε τα παραδείγματα έναντι της εγκατεστημένης έκδοσης του πακέτου πριν τα προσαρμόσετε σε κώδικα παραγωγής.