Μεταφορά από την κλασική ενσωμάτωση .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 με τα εγκεκριμένα αντικείμενα της έκδοσης.

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

Οι κλασικές εφαρμογές δημιουργούν το Viewer με κρυφή μνήμη ASP.NET και εξαρτήσεις πρόσβασης αιτήματος:

// Κλασική ενσωμάτωση — μόνο για αντίθεση· μην το μεταγλωττίσετε με το τρέχον SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

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

Μεσαλφάκια και δρομολόγηση πόρων

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

// Κλασική ενσωμάτωση — αφαιρέστε το κατά τη μετάβαση.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Στο τρέχον pipeline:

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

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

Δόμηση Viewer και διάρκεια ζωής

Αφαιρέστε τις κρυφές μνήμες που ανήκουν στην εφαρμογή για αντικείμενα 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 });
});

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

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

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

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

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

viewer.CloseDocument(token);

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

Κλάσεις διαμόρφωσης

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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