Μεταφορά από την κλασική ενσωμάτωση .NET 6

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

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

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

Γιατί το όνομα του πακέτου NuGet μπορεί να μην σας λέει τίποτα

Και οι δύο γενιές διανέμονται υπό το ίδιο ID πακέτου Doconut.NET6. Μια αναφορά πακέτου, αρχείο κλειδώματος ή αποθηκευμένο .nupkg επομένως δεν προσδιορίζει από μόνο του το API φιλοξενίας. Καταγράψτε την ακριβή έκδοση του πακέτου και εξετάστε τα Program.cs, τη δημιουργία του viewer, το άνοιγμα εγγράφων και τα σενάρια του προγράμματος περιήγησης μαζί.

Η τρέχουσα έκδοση που ελέγχεται για αυτόν τον οδηγό είναι Doconut.NET6 26.7.0. Τα προαιρετικά δημόσια πακέτα της είναι Doconut.NET6.Converter και Doconut.NET6.Dicom, δεσμευμένα στην ίδια έκδοση κυκλοφορίας με το βασικό πακέτο.

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

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

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

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

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

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

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

LicenseStream > LicenseContent > LicensePath > αυτόματη ανακάλυψη

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

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

Εκκίνηση και εξάρτηση injection

Οι κλασικές εφαρμογές δημιουργούν το Viewer με εξαρτήσεις cache και request‑accessor του ASP.NET:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

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

Το Viewer είναι υπηρεσία transient. Ο διαχειριστής συνεδρίας εγγράφου και η cache του κατέχουν την πιο μακράς διάρκειας κατάσταση εγγράφου, όχι η συγκεκριμένη injected παρουσία Viewer.

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

Αφαιρέστε το κλασικό κλαδί MapWhen που εντοπίζει το DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Στο τρέχον pipeline:

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

Το MiddlewarePath είναι επικυρωμένη ρύθμιση· δεν δημιουργεί αυτόματα κλαδί ASP.NET Core. Χρησιμοποιήστε είτε το απλό pipeline στο παραπάνω δείγμα είτε μια ρητή διάταξη app.Map("/doconut", branch => branch.UseDoconut()) που χρησιμοποιείται σταθερά από τον πελάτη.

Δημιουργία Viewer και διάρκεια ζωής

Αφαιρέστε τις cache που ανήκουν στην εφαρμογή για αντικείμενα Viewer. Ενσωματώστε το Viewer σε ένα endpoint, Razor page, controller ή scoped υπηρεσία εφαρμογής:

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

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

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

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

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

viewer.CloseDocument(token);

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

Κλάσεις ρυθμίσεων

Το τρέχον API διαχωρίζει τις ανησυχίες:

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

Γραμμή εργαλείων Viewer, Search και Annotation

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

1. εκπομπή CSS Viewer και αδειοδοτημένου Search/Annotation CSS με ReferenceCss;
2. απόδοση της γραμμής εργαλείων Viewer που ανήκει στην εφαρμογή·
3. απόδοση searchBarMount, annBarMount και του απαιτούμενου mount Viewer·
4. εκπομπή σενάριων Viewer και αδειοδοτημένων modules με ReferenceScripts;
5. φόρτωση του δικού της viewerToolbar.js·
6. αρχικοποίηση ενός objViewer;
7. αρχικοποίηση των αδειοδοτημένων Search και Annotation Ribbons·
8. κλήση attach(objViewer) σε κάθε Ribbon·
9. άνοιγμα του εγγράφου και κλήση objViewer.View(token).

Search και Annotation είναι modules που συνδέονται στον ίδιο Viewer, όχι ανεξάρτητες γραμμές εργαλείων. Η κύρια γραμμή εργαλείων ανήκει στην εφαρμογή‑ξενιστή· τα Ribbons Search και Annotation είναι ενσωματωμένοι, με πόρους που ελέγχονται από δυνατότητες.

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

Καταχώρηση plugin

Οι κλασικές στατικές μέθοδοι άδειας plugin δεν καταχωρούν τα τρέχοντα plugins. Εγκαταστήστε και καταχωρήστε κάθε εκδοθέν πακέτο ρητά:

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

Το AddDoconut() επικυρώνει τις καταχωρημένες δυνατότητες plugin κατά την εκκίνηση. Converter και DICOM είναι εκδοθέντα .NET 6 plugins. Τα κανονικά Search και Annotation είναι ενσωματωμένα αδειοδοτημένα χαρακτηριστικά, όχι πακέτα AddPlugin<TPlugin>().

Συνεδρία και ασφάλεια εγγράφου

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

builder.Services.AddSession();
app.UseSession();

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

Η Distributed reference application προσθέτει εισιτήρια πρόσβασης και λεπτομέρειες μεταφοράς. Αυτά τα API δεν απαιτούνται για μια κανονική μετανάστευση μονού κόμβου.

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

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

• εκκίνηση εφαρμογής με την παραγωγική άδεια και κάθε καταχωρημένο plugin·
• CSS/σενάρια Viewer και όλα τα αιτήματα εικόνας σελίδας κάτω από τις επιλεγμένες διαδρομές·
• άνοιγμα εγγράφου, πλοήγηση, ζουμ, μικρογραφίες, εκτύπωση και ρητό κλείσιμο·
• Search σε έγγραφο με κείμενο και την κατάσταση μη‑αναζητήσιμης εικόνας μόνο·
• φόρτωση, αποθήκευση, εξαγωγή Annotation και έλεγχο δυνατότητας·
• ανακάλυψη στόχου Converter, έξοδο, λήψη και κατάσταση υδατογραφήματος·
• σελίδες DICOM, καρέ και animation· (τα τεχνικά metadata .NET 6 δεν είναι διαθέσιμα)·
• έγγραφα με κωδικό πρόσβασης, προσαρμοσμένες γραμματοσειρές, μη‑λατινικό κείμενο και ρυθμισμένα χρονικά όρια·
• απόρριψη διακριτικού μεταξύ συνεδριών και συμπεριφορά ληγμένης συνεδρίας·
• κινητές συσκευές, dark mode και τη διαδρομή reverse‑proxy παραγωγής.

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

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

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

• το slot ή το artefact ανάπτυξης που χρησιμοποιείται για επαναφορά·
• την επίδραση βάσης δεδομένων/cache, εάν υπάρχει·
• πώς θα ακυρωθούν οι ενεργές συνεδρίες εγγράφων·
• το health check και το δοκιμαστικό έγγραφο που θα χρησιμοποιηθεί για απόφαση επαναφοράς·
• ποιος μπορεί να επαναφέρει το προηγούμενο σύνολο πακέτων και ρυθμίσεων.

Κληρονομική τεκμηρίωση

Το μεταφρασμένο κλασικό εγχειρίδιο παραμένει διαθέσιμο στο Legacy .NET 6 setup. Το νέο Classic integration gateway εξηγεί τα ίδια σήματα αναγνώρισης και συνδέει πίσω σε αυτόν τον οδηγό μετανάστευσης.

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