Μεταφορά σε .NET Standard 2.1

Μετακινήστε μια υπάρχουσα εφαρμογή Doconut.NETStandard από 26.7.0 σε 26.8.0

Το Doconut διαθέτει δύο ξεχωριστές ενσωματώσεις .NET Standard. Χρησιμοποιούν το ίδιο όνομα πακέτου Doconut.NETStandard, επομένως εντοπίστε τη γενιά από την έκδοση και τα API στην εφαρμογή πριν αλλάξετε πακέτα, εκκίνηση, άδειες ή πόρους του προγράμματος περιήγησης.

Η έκδοση είναι το σημείο διαχωρισμού

Και οι δύο γενιές δημοσιεύονται υπό το ίδιο ID πακέτου. Μόνο η έκδοση τις διακρίνει:

ΈκδοσηΣτόχοςAPI
26.7.0 και κάτωnetstandard2.0το προηγούμενο API
26.8.0 και πάνωnetstandard2.1το τρέχον API

Η αύξηση του αριθμού έκδοσης είναι η αναβάθμιση. Δεν υπάρχει ξεχωριστό πακέτο για εγκατάσταση και δεν υπάρχει shim συμβατότητας — το 26.8.0 είναι διαφορετική επιφάνεια API. Περιμένετε σφάλματα μεταγλώττισης μετά την αύξηση· το υπόλοιπο αυτού του οδηγού είναι η λίστα τους.

Ποια ενσωμάτωση χρησιμοποιείτε;

Αν το έργο περιέχει…Γενιά
new Viewer(_cache, _accessor, ...)Προηγούμενη
viewer.OpenDocument(...) (συγχρονισμένο)Προηγούμενη
viewer.InitCache()Προηγούμενη
UseDoconut(new DoconutOptions { ... })Προηγούμενη
UseDoconutWebFarm(...) / WebFarmOptionsΠροηγούμενη
Viewer.DoconutLicense(...) ή Viewer.SetLicensePlugin(...)Προηγούμενη
viewer.Converter.GetConverter()Προηγούμενη
using Doconut.Configs; / using Doconut.Models;Προηγούμενη
Χειροκίνητα αντιγραμμένα docViewer.js, documentLinks.js ή docViewer.UI.jsΠροηγούμενη
builder.Services.AddDoconut(...)Τρέχουσα
app.UseDoconutResources() συν app.UseDoconut() χωρίς ορίσματαΤρέχουσα
Viewer supplied by dependency injectionΤρέχουσα
await viewer.OpenDocumentAsync(...)Τρέχουσα

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

Ελέγξτε πρώτα το πλαίσιο φιλοξενίας

Αυτό είναι ένα σκληρό φράγμα, όχι προτίμηση. Το τρέχον πακέτο στοχεύει στο netstandard2.1:

Πλαίσιο φιλοξενίαςΜπορεί να καταναλώσει 26.8.0
.NET Core 3.0 ή νεότερο (συμπεριλαμβανομένων .NET 5/6/7/8)Ναι
.NET Framework, οποιαδήποτε έκδοσηΌχι

.NET Framework δεν μπορεί να αναφερθεί σε βιβλιοθήκη netstandard2.1. Εάν η εφαρμογή εκτελείται σε .NET Framework, σταματήστε εδώ και χρησιμοποιήστε το πακέτο Doconut.NETFramework αντί αυτού· από το 26.9.0 απαιτεί .NET Framework 4.7.2. Και οι δύο εφαρμογές αναφοράς για αυτήν την έκδοση στοχεύουν στο net8.0.

Πριν τη μετάβαση

  1. Δημιουργήστε ένα κλαδί και ένα αναπληρωματικό αντίγραφο ασφαλείας της υπάρχουσας εφαρμογής που μπορεί να αναπτυχθεί.
  2. Καταγράψτε τις ακριβείς εκδόσεις των βασικών και των πρόσθετων πακέτων.
  3. Καταγράψτε κάθε κλήση new Viewer(...), κλήση InitCache(), κλήση φόρτωσης άδειας, αντιστοίχηση UseDoconutWebFarm, ελεγκτή μετατροπής, αντιγραμμένο σενάριο Doconut, προσαρμοσμένη ενέργεια γραμμής εργαλείων, κλήση επιστροφής viewer και τελικό σημείο ανοίγματος εγγράφου.
  4. Διατηρήστε τα τρέχοντα αρχεία .lic και τα μυστικά ανάπτυξης εκτός ελέγχου πηγαίου κώδικα.
  5. Καταγράψτε ένα αντιπροσωπευτικό σύνολο εγγράφων PDF, Office, εικόνας, CAD, email, DICOM, αναζητήσιμα, προστατευμένα με κωδικό πρόσβασης και σχολιασμένα.
  6. Καταγράψτε το υπάρχον χρονικό όριο συνεδρίας, τη συμπεριφορά ασφαλείας, τις γραμματοσειρές και τις ρυθμίσεις πλατφόρμας.

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

1. Ονοματοχώροι: σχεδόν όλα μεταφέρθηκαν στη ρίζα

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

ΠρινΤώρα
using Doconut.Configs.View;using Doconut;
using Doconut.Models;using Doconut;
using Doconut.Configs;using Doconut;
using Doconut.Configs.Cloud;using Doconut.Clouds;
using Doconut.Configs.Conversion;αμετάβλητο
using Doconut.Middleware;αμετάβλητο

Τα ονόματα τύπων δεν άλλαξαν: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig και τα υπόλοιπα είναι ακόμα εκεί. Στα περισσότερα αρχεία η πλήρης επεξεργασία είναι η διαγραφή δύο γραμμών using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) αφαιρέθηκε και δεν έχει αντικατάσταση σε αυτό το πακέτο. Εάν η εφαρμογή σας αναφερόταν σε αυτούς τους τύπους, προγραμματίστε αυτό το μέρος ξεχωριστά και μην το θεωρήσετε μέρος αυτής της μετάβασης.

2. Συμβατότητα πακέτου και άδειας

Αντικαταστήστε ή ενημερώστε το βασικό πακέτο σκόπιμα· μην βασίζεστε στο ίδιο αναγνωριστικό πακέτου για να επιλέξετε το νέο API. Η προεπιλεγμένη εντολή εγκαθιστά την πιο πρόσφατη σταθερή έκδοση:

bash
dotnet add package Doconut.NETStandard

Για μια επαναλήψιμη μετάβαση στην έκδοση που ελέγχεται από αυτόν τον οδηγό, περάστε την έκδοση ως ξεχωριστή επιλογή:

bash
dotnet add package Doconut.NETStandard --version 26.9.0

Διατηρήστε κάθε πρόσθετο Doconut στην ίδια έκδοση με το βασικό πακέτο — Doconut.NETStandard.Converter και Doconut.NETStandard.Dicom. Η τρέχουσα ενσωμάτωση φορτώνει τις άδειες μία φορά κατά τη διάρκεια του AddDoconut(), χρησιμοποιώντας αυτήν την προτεραιότητα:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Η αυτόματη ανακάλυψη ψάχνει για αρχεία Doconut.Viewer.lic και τα συνοδευτικά αρχεία Doconut.Viewer.<Capability>.lic. Οι προηγούμενες στατικές κλήσεις Viewer.DoconutLicense(...) και Viewer.SetLicensePlugin(...) δεν αποτελούν τρέχον μηχανισμό εκκίνησης, και το ίδιο ισχύει για το List<string> των διαδρομών άδειας που αποδεχόταν ο παλιός κατασκευαστής Viewer. Μετακινήστε την άδεια στο DoconutOptions, κρατήστε τα συνοδευτικά αρχεία μαζί όταν χρησιμοποιείτε την αυτόματη ανακάλυψη, επανεκκινήστε μετά την αλλαγή μιας άδειας και επαληθεύστε τις δυνατότητες μέσω του IDoconutLicenseService.

Μην υποθέτετε ότι η παρουσία μιας παλιάς άδειας πρόσθετου αποδεικνύει δικαίωμα για την τρέχουσα έκδοση του πρόσθετου. Δοκιμάστε το Viewer, το Search, το Annotation, το Converter και το DICOM ξεχωριστά με τα εγκεκριμένα αντικείμενα της έκδοσης.

3. Εκκίνηση και ενσωμάτωση εξαρτήσεων

Προηγουμένως, το Viewer δημιουργούνταν ανά αίτημα και οι επιλογές περνούσαν στο middleware:

csharp
// Προηγούμενη ενσωμάτωση — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

Η τρέχουσα ενσωμάτωση καταχωρεί το Doconut μία φορά και λαμβάνει Viewer από την ενσωμάτωση εξαρτήσεων:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // σημειώστε την αλλαγή ορθογραφίας: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // η κατάσταση συνεδρίας χρειάζεται μια κρυφή μνήμη (MVC/Razor Pages ήδη προσθέτουν μία)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

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

Τρία πράγματα που πρέπει να διατηρηθούν:

  • new Viewer(cache, accessor) έχει αφαιρεθεί. Ενσωματώστε Doconut.Viewer στον ελεγκτή σας, ή χρησιμοποιήστε @inject Doconut.Viewer Viewer σε μια Razor προβολή.
  • UseDoconutResources() αντικαθιστά την χειροκίνητη σύνδεση app.UseMiddleware<EmbeddedResourceMiddleware>(), και πρέπει να εκτελείται πριν από το κλαδί του εγγράφου.
  • UnSafeMode → UnsafeMode. Μία μετονομασία ενός χαρακτήρα που θα εντοπίσει ο μεταγλωττιστής.

Όταν το UnsafeMode είναι false, το SDK επικυρώνει το διακριτικό συνεδρίας σε σχέση με το αρχικό αίτημα, έτσι τα AddSession() / UseSession() πρέπει να παραμένουν στην αλυσίδα επεξεργασίας, UseSession() πριν από το κλαδί.

Μέθοδοι που δεν υπάρχουν πλέον

ΠρινΤώρα
viewer.OpenDocument(path, config, options)await viewer.OpenDocumentAsync(path, config, options)
viewer.InitCache()αφαιρεμένο — δεν υπάρχει τίποτα για χειροκίνητη προθέρμανση· διαγράψτε την κλήση και οποιαδήποτε σημαία «ήδη εκκίνησα;» γύρω της
viewer.ExportToPng(sharedPath)βλ. §7
viewer.ExportToCloud(cloudConfig)βλ. §7
using var v = new Viewer(...); v.CloseDocument(t)viewer.CloseDocument(token) στο ενσωματωμένο παράδειγμα

4. Middleware και δρομολόγηση πόρων

UseDoconut() τώρα δεν δέχεται ορίσματα. Η μορφή του κλαδιού MapWhen δεν χρειάζεται να αλλάξει — μόνο το middleware μέσα σε αυτό:

csharp
app.UseDoconutResources();   // ΠΡΙΝ το branch

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

Στην τρέχουσα αλυσίδα επεξεργασίας:

  1. καλέστε UseSession() πριν από το Doconut ενώ η ασφάλεια συνεδρίας είναι ενεργοποιημένη·
  2. καλέστε UseDoconutResources() πριν από UseDoconut()·
  3. διατηρήστε το ResourcesPath, τις παραγόμενες διευθύνσεις URL πόρων, και τον πελάτη ResPath ευθυγραμμισμένα·
  4. διατηρήστε το κλαδί που χαρτογραφείτε και τον πελάτη BasePath ευθυγραμμισμένα.

MiddlewarePath είναι επικυρωμένη διαμόρφωση· δεν δημιουργεί κλαδί ASP.NET Core από μόνο του.

5. Κατασκευή και διάρκεια λειτουργίας του Viewer

Αφαιρέστε τις κρυφές μνήμες που ανήκουν στην εφαρμογή για αντικείμενα τύπου Viewer. Δεν απομένει τίποτα σε ένα Viewer που αξίζει να διατηρηθεί: δεν μεταφέρει καμία κατάσταση εγγράφου, και η κρυφή μνήμη συνεδρίας κατέχει ό,τι υπέρχει από ένα αίτημα. Ενσωματώστε το σε ένα endpoint, Razor page, controller ή scoped υπηρεσία εφαρμογής:

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Το επιστρεφόμενο token αναγνωρίζει μια συνεδρία εγγράφου στο διακομιστή. Θεωρήστε το ως διακριτικό τύπου bearer: μην το καταγράφετε, μην το αποθηκεύετε μόνιμα και μην το τοποθετείτε σε αναλύσεις.

6. Άνοιγμα και κλείσιμο εγγράφων

Αντικαταστήστε το συγχρονικό OpenDocument(...) με το OpenDocumentAsync(...):

csharp
// Τρέχουσα ενσωμάτωση: ο Viewer προέρχεται από DI και το άνοιγμα του εγγράφου είναι ασύγχρονο.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Οι τρέχουσες υπερφορτώσεις δέχονται διαδρομή αρχείου ή ροή, προαιρετική διαμόρφωση μορφής, προαιρετικό DocOptions και ένα token ακύρωσης. Κλείστε ρητά τη συνεδρία του διακομιστή όταν ο περιηγητής δεν τη χρειάζεται πλέον:

csharp
viewer.CloseDocument(token);

Διαγράψτε οποιαδήποτε κλήση InitCache() και τη σημαία που την προστατεύει — δεν υπάρχει τίποτα που χρειάζεται προθέρμανση με το χέρι. Μην επαναχρησιμοποιήσετε ένα token που δημιουργήθηκε από την προηγούμενη βιβλιοθήκη μετά τη μετάβαση: ανοίξτε ξανά κάθε έγγραφο μέσω του τρέχοντος API.

7. Web farm → distributed: η μεγαλύτερη αλλαγή

UseDoconutWebFarm και WebFarmOptions δεν υπάρχουν πλέον. Εάν η εφαρμογή σας τα καλεί, αυτή η ενότητα είναι η αναβάθμισή σας· αν όχι, παραλείψτε στο §8.

Προηγουμένως, ένα middleware έκανε τα πάντα: σερβίριζε προ-αποδομημένες εικόνες από έναν κοινόχρηστο φάκελο, και έλεγχε περιοδικά ενώ ένας άλλος κόμβος συνέχιζε να τις γράφει.

csharp
// Προηγούμενη ενσωμάτωση — μία κλήση, έμμεση συντονισμός μέσω του συστήματος αρχείων.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

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

csharp
var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, ενσωματωμένο από DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // ο ίδιος φάκελος που χρησιμοποιείς σήμερα
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Μέρος ανάγνωσης — οποιοσδήποτε κόμβος εξυπηρετεί από το κοινόχρηστο:

csharp
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* το ίδιο FileShareConfig όπως παραπάνω */;
    }, "/"));
ΠρινΤώρα
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageαπενεργοποιημένο — αντικατεστημένο από FirstPagePriority στην πλευρά εγγραφής και FileShareConfig.ReadReadyPollMs στην πλευρά ανάγνωσης
viewer.OpenDocument(...) τότε viewer.ExportToPng(share)μία κλήση PublishAsync(...)
DocOptions.IsWebfarm / WebfarmPathεξακολουθεί να υπάρχει, γραμμένο ως IsWebFarm / WebFarmPath — αλλά δεν χρειάζεται στη διαδρομή δημοσίευσης

Η τοπολογία σας δεν αλλάζει. Κατευθύνετε το RootPath προς το ίδιο UNC share και κάθε κόμβος συνεχίζει να λειτουργεί όπως λειτουργεί σήμερα. Η αλλαγή είναι ότι η δημοσίευση είναι μια λειτουργία που καλείτε, αντί για παρενέργεια της απόδοσης.

Και οι δύο μισές πρέπει να συμφωνούν. Εάν RootPath ή UsePerTokenSubfolders διαφέρουν μεταξύ του publisher και του handler, ο άλλος κόμβος επιστρέφει 404. Δημιουργήστε τη διαμόρφωση σε έναν βοηθό και καλέστε την και από τις δύο πλευρές.

PageWaitTimeSeconds = 180 σήμαινε «αποκλεισμός έως τρία λεπτά ελπίζοντας να εμφανιστεί η σελίδα». Η αντικατάσταση είναι σαφής: με το FirstPagePriority = true, η σελίδα 1 είναι άμεσα εξυπηρετήσιμη και οι επόμενες σελίδες απαντούν HTTP 202 Accepted μέχρι να γραφτούν. Ο ενσωματωμένος viewer επαναπροσπαθεί αυτόματα όταν το retryOn409 είναι ενεργοποιημένο. Ένας πελάτης που δεν επαναπροσπαθεί θα δείξει σπασμένα πλακίδια για σελίδες που εξακολουθούν να αποδίδονται.

Η πλήρης διάταξη, συμπεριλαμβανομένης της παρασκηνιακής δημοσίευσης και των εισιτηρίων πρόσβασης, βρίσκεται στο Διανεμημένες Αναπτύξεις.

8. Η μετατροπή είναι ένα plugin, και πολύ μικρότερο

Καταχωρίστε το plugin, έπειτα ενσωματώστε τη διεπαφή DocumentConverter:

csharp
builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());
csharp
// Προηγούμενη ενσωμάτωση
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Τρέχουσα ενσωμάτωση
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Τι αντικαθιστά αυτό:

  • SourceFormatConverter — αφαιρέθηκε. Περνάτε την επέκταση αρχείου ως συμβολοσειρά, συμπεριλαμβανομένου του τελείας.
  • Οι τύποι *ConfigConverter ανά οικογένεια (WordConfigConverter, ExcelConfigConverter, …), καθένας με ενσωματωμένο enum EnTargetFormat — αφαιρέθηκε. Τώρα υπάρχει ένα enum ConversionTarget για κάθε οικογένεια.
  • viewer.Converter.GetConverter() — αφαιρέθηκε. Ενσωματώστε Doconut.DocumentConverter.

ConvertAsync επιστρέφει ένα ρεύμα με δυνατότητα αναζήτησης, έτσι return File(result, mime, name) λειτουργεί άμεσα — η αντιγραφή του παλιού κώδικα MemoryStream δεν είναι απαραίτητη. Στο παραδιδόμενο δείγμα αυτό διέγραψε μια εναλλαγή 68 περιπτώσεων επέκτασης και δέκα σχεδόν πανομοιότυπους ελεγκτές.

Δείτε το Converter Plugin για την πλήρη λειτουργικότητα.

9. Πάροχοι cloud

UseDoconutCloud έγινε γενικό. Ο πάροχος είναι το όρισμα τύπου αντί για μια τιμή Location που ελέγχεται μέσα στο middleware:

csharp
// Προηγούμενη ενσωμάτωση
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Τρέχουσα ενσωμάτωση
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Οι κλάσεις διαμόρφωσης παραμένουν αμετάβλητες εκτός από το namespace (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, συν το νέο FileShareConfig. Οι χειριστές ονομάζονται <Provider>CloudHandler.

Ο χειριστής CDN είναι μόνο για ανάγνωση — εξυπηρετεί ό,τι είναι ήδη στο CDN· δεν κάνει ανέβασμα.

10. Αντικείμενα διαμόρφωσης που άλλαξαν όνομα

ΠρινΤώρα
DoconutOptions.UnSafeModeUnsafeMode
DocOptions.IsWebfarmIsWebFarm
DocOptions.WebfarmPathWebFarmPath
DocOptions.ImageResolutionεξακολουθεί να υπάρχει αλλά παρωχημένο — ορίστε την ανάλυση στη διαμόρφωση μορφής αντί για αυτό

DocOptions κερδίζει επίσης IsSecured.

Το τρέχον API επίσης διαχωρίζει τις ανησυχίες πιο αυστηρά από το προηγούμενο, οπότε ελέγξτε ότι κάθε ρύθμιση βρίσκεται στο αντικείμενο που το κατέχει τώρα:

ΑνησυχίαΤρέχον τύπο
Διαδρομές middleware, αδειοδότηση, καταχώριση pluginDoconutOptions
Κωδικός πρόσβασης, χρονικό όριο, ασφάλεια, υδατογράφημαDocOptions
Απόδοση μορφής και DPIPdfConfig, WordConfig, ExcelConfig, και άλλοι τύποι BaseConfig
Προεπιλογές widget προγράμματος περιήγησηςViewerConfig ή οι ισοδύναμες επιλογές JavaScript
Δημιουργημένο CSS και scriptsCssConfig και ScriptConfig
Κοινόχρηστη αποθήκευση και πάροχοι cloudFileShareConfig και οι άλλες διαμορφώσεις Doconut.Clouds

Μην προωθήσετε το DocOptions.ImageResolution ως τον έλεγχο απόδοσης. Είναι παρωχημένο· ορίστε το BaseConfig.ImageResolution στη διαμόρφωση ειδική για τη μορφή. Εξετάστε όλες τις προεπιλογές αντί να υποθέτετε ότι μια προηγούμενη διαμόρφωση έχει την ίδια συμπεριφορά.

11. Ο προβολέας στην πλευρά του πελάτη — δύο αλλαγές που αποτυγχάνουν ΣΙΩΠΑ

Και τα δύο αφήνουν τον διακομιστή να λειτουργεί τέλεια. Το έγγραφό σας αποδίδει, η σελίδα φαίνεται σωστή, και δεν εμφανίζεται τίποτα στην κονσόλα του προγράμματος περιήγησης. Διαβάστε αυτήν την ενότητα ακόμη και αν το C# σας μεταγλωττίζει με την πρώτη προσπάθεια.

Οι κλήσεις επιστροφής του προβολέα είναι τώρα επιλογές, όχι παγκόσμιες συναρτήσεις

Ο προηγούμενος προβολέας κάλεσε τους χειριστές σας με όνομα, προεξάγοντας το όνομα της παγκόσμιας συνάρτησης από το αναγνωριστικό του container. Η δήλωση του function ctlDoc_OnViewerReady() σε μια σελίδα με <div id="div_ctlDoc"> ήταν αρκετή. Ο τρέχων προβολέας δέχεται ρητές κλήσεις επιστροφής στο αντικείμενο επιλογών και δεν ψάχνει πλέον για αυτές τις παγκόσμιες μεταβλητές:

javascript
objctlDoc = $("#div_ctlDoc").docViewer({
    // ... οι υπάρχουσες επιλογές σας ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // βρέθηκε με όνομα
    onViewerReady:    ctlDoc_OnViewerReady,     // βρέθηκε με όνομα
    onCopy:           ctlDoc_Copy,              // ήταν ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // ήταν ctlDoc_AutoLoadStatus(page)
});

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

Η πλήρης λίστα επιλογών είναι onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown, και onError. Δεν υπάρχει κλήση επιστροφής για κλικ σε σύνδεσμο: η διαχείριση υπερσυνδέσμων είναι ενσωματωμένη, καθοδηγούμενη από showHyperlinks.

ResPath πρέπει να δείχνει στο πρόθεμα του πόρου

javascript
ResPath: '',                      // ΠΡΙΝ — οι πόροι προέρχονταν από τη ρίζα της εφαρμογής
ResPath: 'doconut-res/images',    // ΤΩΡΑ    — το πρόθεμα UseDoconutResources() τοποθετεί

Αν αλλάξατε το πρόθεμα μέσω DoconutOptions.ResourcesPath, χρησιμοποιήστε αυτήν την τιμή αντ' αυτού.

12. Γραμμή εργαλείων Viewer, Αναζήτηση και Σχόλιο

Μην μεταφέρετε τα παλιά σενάρια ένα-ένα. Οι τρέχουσες εφαρμογές αναφοράς συνθέτουν ένα πλήρες πακέτο σελίδας:

  1. εκδώστε Viewer CSS και αδειοδοτημένο Search/Annotation CSS με ReferenceCss;
  2. απεικονίστε τη γραμμή εργαλείων Viewer που ανήκει στην εφαρμογή;
  3. απεικονίστε searchBarMount, annBarMount, και την απαιτούμενη προσάρτηση Viewer;
  4. εκδώστε Viewer και αδειοδοτημένα scripts μονάδων με ReferenceScripts;
  5. φορτώστε το script βοηθού γραμμής εργαλείων της εφαρμογής;
  6. αρχικοποιήστε ένα objViewer;
  7. αρχικοποιήστε τις αδειοδοτημένες Λωρίδες Αναζήτησης και Σχολίων;
  8. καλέστε attach(objViewer) σε κάθε Λωρίδα;
  9. ανοίξτε το έγγραφο και καλέστε objViewer.View(token).

Η Αναζήτηση και τα Σχόλια είναι μονάδες που συνδέονται στον ίδιο Viewer, όχι ανεξάρτητες γραμμές εργαλείων. Η κύρια γραμμή εργαλείων ανήκει στην εφαρμογή-ξενιστή· οι Λωρίδες Αναζήτησης και Σχολίων είναι ενσωματωμένοι, πόρους με περιορισμένη δυνατότητα.

Αφαιρέστε τα χειροκίνητα αντιγραμμένα αρχεία όπως documentLinks.js και docViewer.UI.js μόνο μετά που η τρέχουσα σελίδα λειτουργεί με πόρους που εκδίδονται από ReferenceCss και ReferenceScripts.

13. Καταχώριση plugin

Οι στατικές μέθοδοι plugin-license δεν καταγράφουν τα τρέχοντα plugins. Εγκαταστήστε και καταχωρίστε κάθε εκδιδόμενο πακέτο ρητά:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() επικυρώνει τις καταχωρημένες δυνατότητες plugin κατά την εκκίνηση. Τα Converter και DICOM είναι τα εκδιδόμενα plugins .NET Standard. Η κανονική Αναζήτηση και τα Σχόλια είναι ενσωματωμένα αδειοδοτημένα χαρακτηριστικά, όχι πακέτα AddPlugin<TPlugin>().

14. Ασφάλεια συνεδρίας και εγγράφου

Η τρέχουσα ενσωμάτωση συνδέει τα έγγραφα με αδιαφανή διακριτικά και αποθηκευμένες συνεδρίες. Με το προεπιλεγμένο UnsafeMode = false, το UseDoconut() προσθέτει ασφάλεια πρόσβασης εγγράφου και ο ξενιστής πρέπει να διαμορφώσει τη συνεδρία ASP.NET:

csharp
builder.Services.AddDistributedMemoryCache(); // η κατάσταση συνεδρίας χρειάζεται μια κρυφή μνήμη (MVC/Razor Pages ήδη προσθέτει μία)
builder.Services.AddSession();
app.UseSession();

Διατηρήστε το DocOptions.IsSecured = true εκτός εάν ένα ελεγμένο σχέδιο απαιτεί το αντίθετο. Ποτέ μην χρησιμοποιείτε το UnsafeMode = true ως συντόμευση μετεγκατάστασης σε έναν μόνο κόμβο. Δοκιμάστε αιτήματα χωρίς διακριτικό, με κατεστραμμένο διακριτικό, με ληγμένο διακριτικό, και με διακριτικό από διαφορετική συνεδρία προγράμματος περιήγησης.

Σε ένα farm, το αίτημα σελίδας μπορεί να καταλήξει σε έναν κόμβο που δεν είδε ποτέ το αρχικό αίτημα, έτσι ο έλεγχος ανά συνεδρία θα το απορρίψει. Αυτή είναι η μόνη περίπτωση όπου το UnsafeMode = true είναι σωστό — και πρέπει να συνδυάζεται με υπογεγραμμένα εισιτήρια πρόσβασης μέσω του AddDoconutDistributedDocumentSecurity, όχι να αποστέλλεται μόνο του. Δείτε Διανεμημένες Αναπτύξεις.

Σημείωση ονομασίας

Σε όλα τα πλαίσια, η κλάση είναι Viewer. Αν βρείτε DocumentViewer σε παλιές αποσπάσεις κώδικα ή άρθρα τρίτων, αυτός ο τύπος δεν υπήρχε ποτέ στο SDK.

15. Προτεινόμενη σειρά εργασιών

  1. Επιβεβαιώστε ότι το πλαίσιο-ξενιστής μπορεί να καταναλώσει netstandard2.1. Αν δεν μπορεί, σταματήστε.
  2. Αναβαθμίστε το πακέτο στην έκδοση 26.8.0 και κάντε build. Εργαστείτε μέσα από τα σφάλματα μεταγλώττισης — τα περισσότερα είναι οι γραμμές using στο §1.
  3. Μετακινήστε την εκκίνηση στο AddDoconut() και τις κλήσεις middleware στη νέα τους σειρά (§3, §4).
  4. Ενσωματώστε το Viewer εκεί που το κατασκευάζατε, κάντε το OpenDocument ασύγχρονο, και διαγράψτε το InitCache() (§5, §6).
  5. Αν χρησιμοποιείτε το web farm, κάντε το §7 — το μοναδικό μέρος που είναι επανασχεδίαση αντί για μετονομασία.
  6. Αν μετατρέπετε έγγραφα, κάντε το §8.
  7. Κάντε το §11 — τις αλλαγές στην πλευρά του πελάτη. Είναι αυτές που δεν θα ανακοινώσουν τον εαυτό τους.
  8. Ανοίξτε ένα πραγματικό έγγραφο σε πρόγραμμα περιήγησης και παρακολουθήστε το περιστρεφόμενο δείκτη φόρτωσης. Μια πράσινη κατασκευή δεν αποδεικνύει τίποτα εδώ: η αδειοδότηση, η καταχώριση plugin, η διαδρομή πόρων και τα callbacks του viewer αποτυγχάνουν μόνο σε χρόνο εκτέλεσης. Για ένα farm, επαληθεύστε ότι ένα έγγραφο που δημοσιεύτηκε από έναν κόμβο εξυπηρετείται από έναν άλλο.

Δοκιμή της μετανάστευσης

Στο ελάχιστο, επαληθεύστε:

  • εκκίνηση της εφαρμογής με την άδεια παραγωγής και κάθε καταχωρημένο πρόσθετο·
  • CSS/σενάρια του Προβολέα και όλα τα αιτήματα σελίδας‑εικόνας κάτω από τις επιλεγμένες διαδρομές·
  • άνοιγμα εγγράφου, πλοήγηση, ζουμ, μικρογραφίες, εκτύπωση και ρητό κλείσιμο·
  • Αναζήτηση σε έγγραφο με κείμενο και η μη αναζητήσιμη κατάσταση αρχείου μόνο με εικόνα·
  • φόρτωση, αποθήκευση, εξαγωγή σχολίων και περιορισμός λειτουργιών·
  • ανακάλυψη στόχου μετατροπέα, έξοδος, λήψη και κατάσταση υδατογραφήματος·
  • σελίδες DICOM, καρέ και animation· η τεχνική μεταδεδομένα δεν είναι διαθέσιμα σε αυτό το πακέτο·
  • έγγραφα με προστασία κωδικού, προσαρμοσμένες γραμματοσειρές, μη λατινικό κείμενο και ρυθμισμένα χρονικά όρια·
  • απόρριψη token διασυνεδρίας και συμπεριφορά ληγμένης συνεδρίας·
  • για ένα farm: δημοσίευση σε έναν κόμβο, αίτηση μιας καθυστερημένης σελίδας από έναν άλλο, και επιβεβαίωση του
    προβολέα ότι επαναπροσπαθεί τις απαντήσεις 202 αντί να εμφανίζει σπασμένα πλακίδια·
  • κινητό, σκοτεινή λειτουργία και η διαδρομή αντίστροφου μεσολαβητή παραγωγής·

Σχέδιο επαναφοράς

Διατηρήστε το προηγούμενο αντικείμενο ανάπτυξης, τα αντίστοιχα πακέτα, τα αρχεία άδειας και τους αντιγραμμένους πόρους του προγράμματος περιήγησης
συνολικά. Μια ασφαλής επαναφορά αλλάζει ολόκληρη τη γενιά της εφαρμογής· δεν κάνει
ανάμειξη διακομιστή προηγούμενης γενιάς με τρέχοντα σενάρια, ή τρέχοντα διακομιστή με
new Viewer(...) σημεία κλήσης.

Πριν από τη μετάβαση, τεκμηριώστε:

  • το slot ή το αντικείμενο ανάπτυξης που χρησιμοποιείται για επαναφορά·
  • την επίπτωση του κοινόχρηστου αποθηκευτικού χώρου, εάν υπάρχει — τα αντικείμενα που δημοσιεύτηκαν από την έκδοση 26.8.0 δεν καταναλώνονται από το προηγούμενο middleware του web‑farm·
  • πώς οι ενεργές συνεδρίες εγγράφων θα ακυρωθούν·
  • τον έλεγχο υγείας και το δοκιμαστικό έγγραφο που χρησιμοποιείται για την απόφαση επαναφοράς·
  • ποιος μπορεί να επαναφέρει το προηγούμενο σύνολο πακέτων και τη διαμόρφωση.

Τεκμηρίωση κληρονομιάς

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

Διατηρήστε το ιστορικό URL σε σελιδοδείκτες και αιτήματα υποστήριξης ενώ οι εγκαταστάσεις netstandard2.0 εξακολουθούν να υπάρχουν. Καταγράφει μια διαφορετική γενιά και δεν ανακατευθύνεται στο τρέχον API.

Ήταν αυτή η σελίδα χρήσιμη;