Εκπαίδευση: Άνοιγμα Εγγράφων με τον Ενσωματωμένο Προβολέα Doconut σε .NET 8

Εισαγωγή

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

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

---

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

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

dotnet add package Doconut.NET8

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

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 του στοιχείου.

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>

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

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 υπηρεσία. Λάβετε το μέσω injection στα endpoints, injection κατασκευαστή ή της αντίστοιχης δυνατότητας στην εφαρμογή 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. Μεταφορά του διακριτικού στο στοιχείο

Ανακτήστε το 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));

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

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

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

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

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

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

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

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

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()
Static license-loading calls in request code	Διαμορφώστε την είσοδο άδειας στο AddDoconut()
Synchronous OpenDocument(...) examples	Χρησιμοποιήστε το OpenDocumentAsync(...)
An external or invented viewer CDN	Εκδώστε ενσωματωμένους πόρους με ReferenceCss και ReferenceScripts
A generic JavaScript init() API	Αρχικοποιήστε το $('#div_ctlDoc').docViewer(...)
Persisting the viewer token	Διατηρήστε το αναγνωριστικό του εγγράφου· αντιμετωπίστε το διακριτικό ως προσωρινό

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