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

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

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

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

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

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

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

Πριν κάνετε τη μεταφορά

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

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

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

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

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

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

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

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

Classic applications construct Viewer with ASP.NET cache and request-accessor dependencies:

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

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

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

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

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

Μεσαίωση (Middleware) και δρομολόγηση πόρων

Remove the classic MapWhen branch that detects DocImage.axd:

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

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

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

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

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

Remove application‑owned caches of Viewer objects. Ενσωματώστε το Viewer σε ένα endpoint, Razor page, controller ή scoped application service:

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

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

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

Replace synchronous OpenDocument(...) with OpenDocumentAsync(...):

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

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

viewer.CloseDocument(token);

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

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

The current API separates concerns:

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

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

Do not migrate the old scripts one by one. Οι τρέχουσες εφαρμογές‑αναφοράς συνθέτουν ένα πλήρες πακέτο σελίδας:

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

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

Remove manually copied classic files such as documentLinks.js and docViewer.UI.js only after the current page works with resources emitted by ReferenceCss and ReferenceScripts.

Καταχώρηση πρόσθετου

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

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

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

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

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

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

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

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

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

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

• εκκίνηση εφαρμογής με την άδεια παραγωγής και κάθε καταχωρημένο πρόσθετο·
• CSS/σενάρια Viewer και όλα τα αιτήματα σελίδας‑εικόνας κάτω από τις επιλεγμένες διαδρομές·
• άνοιγμα εγγράφου, πλοήγηση, ζουμ, μικρογραφίες, εκτύπωση και ρητό κλείσιμο·
• Αναζήτηση σε έγγραφο που περιέχει κείμενο και η μη‑αναζητήσιμη κατάσταση ενός αρχείου μόνο με εικόνα·
• Φόρτωση, αποθήκευση, εξαγωγή και περιορισμός λειτουργιών Σχολίου·
• Ανακάλυψη στόχου Converter, έξοδος, λήψη και κατάσταση υδατογραφήματος·
• Σελίδες DICOM, καρέ και animation· .NET 6 τεχνικά μεταδεδομένα δεν είναι διαθέσιμα·
• έγγραφα με προστασία κωδικού, προσαρμοσμένες γραμματοσειρές, μη‑λατινικό κείμενο και ρυθμισμένα χρονικά όρια·
• απόρριψη διακριτικού μεταξύ συνεδριών και συμπεριφορά ληγμένης συνεδρίας·
• κινητές συσκευές, σκοτεινή λειτουργία και η διαδρομή reverse‑proxy παραγωγής.

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

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

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

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

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

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

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