Migracja z klasycznej integracji .NET 6

Doconut ma dwie odrębne integracje .NET 6. Mogą używać tej samej nazwy pakietu Doconut.NET6, więc zidentyfikuj generację na podstawie API w aplikacji przed zmianą pakietów, uruchamiania, licencji lub zasobów przeglądarki.

Którą integrację .NET 6 używasz?

Jeśli obie kolumny pojawiają się w tej samej aplikacji, traktuj migrację jako niekompletną. Nie wysyłaj jednego tokenu dokumentu przez zasoby lub middleware z innej generacji.

Dlaczego nazwa pakietu NuGet może nie wystarczyć

Obie generacje zostały opublikowane pod identyfikatorem pakietu Doconut.NET6. Odwołanie do pakietu, plik lock lub buforowany .nupkg nie identyfikują więc same w sobie hostowanego API. Zanotuj dokładną wersję pakietu i sprawdź Program.cs, konstrukcję viewer, otwieranie dokumentów oraz skrypty przeglądarki razem.

Bieżąca wersja audytowana dla tego przewodnika to Doconut.NET6 26.7.0. Jej opcjonalne publiczne pakiety to Doconut.NET6.Converter i Doconut.NET6.Dicom, przypięte do tej samej wersji wydania co pakiet podstawowy.

Przed migracją

1. Utwórz gałąź i wdrażalną kopię zapasową istniejącej aplikacji.
2. Zanotuj dokładne wersje pakietów podstawowego i wtyczek.
3. Zrób inwentaryzację każdego mapowania DocImage.axd, wywołania new Viewer(...), wywołania ładowania licencji, skopiowanego skryptu Doconut, niestandardowej akcji paska narzędzi i punktu końcowego otwierania dokumentu.
4. Zachowaj bieżące pliki .lic oraz sekrety wdrożeniowe poza kontrolą wersji.
5. Zbierz reprezentatywny zestaw dokumentów PDF, Office, obrazów, CAD, e‑mail, DICOM, przeszukiwalnych, chronionych hasłem i anotowanych.
6. Zanotuj istniejące limity czasu sesji, zachowanie zabezpieczeń, czcionki i ustawienia platformy.

Migruj jedno środowisko przed zmianą produkcji. Bieżąca integracja zmienia czas życia usług, routing żądań, własność sesji oraz dostarczanie zasobów klienta.

Zgodność pakietów i licencji

Zamień lub zaktualizuj pakiet podstawowy celowo; nie polegaj na identycznym identyfikatorze pakietu, aby wybrać nowe API. Domyślne polecenie instaluję najnowsze stabilne wydanie:

dotnet add package Doconut.NET6

Aby uzyskać powtarzalną migrację do wersji audytowanej w tym przewodniku, przekaż wersję jako oddzielną opcję:

dotnet add package Doconut.NET6 --version 26.7.0

Utrzymuj wszystkie wtyczki Doconut w tej samej wersji co pakiet podstawowy. Bieżąca integracja ładuje licencje raz podczas AddDoconut(), używając tego priorytetu:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatyczne wykrywanie szuka Doconut.Viewer.lic i powiązanych plików Doconut.Viewer.<Capability>.lic. Klasyczne wywołanie Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...) nie jest bieżącym mechanizmem uruchamiania. Przenieś licencję do DoconutOptions, trzymaj powiązane pliki razem przy użyciu automatycznego wykrywania, uruchom ponownie po zmianie licencji i zweryfikuj możliwości poprzez IDoconutLicenseService.

Nie zakładaj, że obecność starej licencji wtyczki uprawnia do bieżącej wersji wtyczki. Testuj osobno Viewer, Search, Annotation, Converter i DICOM przy użyciu zatwierdzonych artefaktów wydania.

Rozruch i wstrzykiwanie zależności

Klasyczne aplikacje tworzą Viewer przy użyciu pamięci podręcznej ASP.NET i zależności request-accessor:

// Klasyczna integracja — tylko kontrast; nie kompiluj tego z bieżącym SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Obecna integracja rejestruje Doconut raz i otrzymuje Viewer z wstrzykiwania zależności:

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 jest usługą przejściową. Menedżer sesji dokumentu i jego pamięć podręczna zarządzają długotrwałym stanem dokumentu, a nie konkretną wstrzykniętą instancją Viewer.

Middleware i routing zasobów

Usuń klasyczną gałąź MapWhen, która wykrywa DocImage.axd:

// Klasyczna integracja — usuń podczas przejścia.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

W bieżącym potoku:

1. wywołaj UseSession() przed Doconut, gdy zabezpieczenie sesji jest włączone;
2. wywołaj UseDoconutResources() przed UseDoconut();
3. utrzymaj ResourcesPath, wygenerowane adresy URL zasobów oraz klienta ResPath w zgodzie;
4. przy mapowaniu UseDoconut() na gałąź, utrzymaj tę gałąź i klienta BasePath w zgodzie.

MiddlewarePath jest zweryfikowaną konfiguracją; nie tworzy ona samodzielnie gałęzi ASP.NET Core. Użyj albo prostego potoku w powyższym przykładzie kompilacji, albo wyraźnego układu app.Map("/doconut", branch => branch.UseDoconut()) stosowanego konsekwentnie przez klienta.

Budowa i cykl życia przeglądarki

Usuń pamięci podręczne własności aplikacji dla obiektów Viewer. Wstrzyknij Viewer do punktu końcowego, strony Razor, kontrolera lub usługi aplikacji o zasięgu:

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

Zwrócony token identyfikuje sesję dokumentu po stronie serwera. Traktuj go jako poświadczenie typu bearer: nie loguj go, nie przechowuj ani nie umieszczaj w analizach.

Otwieranie i zamykanie dokumentów

Zastąp synchroniczny OpenDocument(...) przez OpenDocumentAsync(...):

// Obecna integracja .NET 6: Viewer pochodzi z DI, a otwieranie dokumentu jest asynchroniczne.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Obecne przeciążenia akceptują ścieżkę pliku lub strumień, opcjonalną konfigurację formatu, opcjonalny DocOptions oraz token anulowania. Zamknij sesję serwera explicite, gdy przeglądarka już jej nie potrzebuje:

viewer.CloseDocument(token);

Nie używaj ponownie klasycznego tokenu po przejściu. Otwórz każdy dokument ponownie za pomocą bieżącego API.

Klasy konfiguracji

Obecne API rozdziela obszary odpowiedzialności:

Nie przenoś DocOptions.ImageResolution jako kontrolki renderowania. Jest ona przestarzała; ustaw BaseConfig.ImageResolution w konfiguracji specyficznej dla formatu. Przejrzyj wszystkie domyślne ustawienia zamiast zakładać, że klasyczna konfiguracja zachowuje się tak samo.

Pasek narzędzi przeglądarki, wyszukiwanie i adnotacje

Nie migruj starych skryptów pojedynczo. Obecne aplikacje referencyjne tworzą kompletny pakiet strony:

1. generuj CSS Viewer oraz licencjonowany CSS Search/Annotation przy użyciu ReferenceCss;
2. renderuj pasek narzędzi Viewer będący własnością aplikacji;
3. renderuj searchBarMount, annBarMount oraz wymaganą montaż Viewer;
4. generuj skrypty Viewer i licencjonowanych modułów przy użyciu ReferenceScripts;
5. załaduj własny viewerToolbar.js aplikacji;
6. zainicjuj jeden objViewer;
7. zainicjuj licencjonowane wstążki Search i Annotation;
8. wywołaj attach(objViewer) na każdej wstążce;
9. otwórz dokument i wywołaj objViewer.View(token).

Search i Annotation są modułami podłączonymi do tego samego Viewer, a nie niezależnymi paskami narzędzi. Główny pasek narzędzi należy do aplikacji hosta; wstążki Search i Annotation są osadzone, zasoby kontrolowane możliwościami.

Usuń ręcznie skopiowane klasyczne pliki, takie jak documentLinks.js i docViewer.UI.js, dopiero po tym, jak bieżąca strona będzie działać z zasobami emitowanymi przez ReferenceCss i ReferenceScripts.

Rejestracja wtyczki

Klasyczne statyczne metody licencjonowania wtyczek nie rejestrują bieżących wtyczek. Zainstaluj i zarejestruj każdy wydany pakiet explicite:

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

AddDoconut() weryfikuje zarejestrowane możliwości wtyczek przy uruchamianiu. Converter i DICOM są wydanymi wtyczkami .NET 6. Normal Search i Annotation są wbudowanymi funkcjami licencjonowanymi, a nie pakietami AddPlugin<TPlugin>().

Bezpieczeństwo sesji i dokumentu

Obecna integracja wiąże dokumenty z nieprzezroczystymi tokenami i buforowanymi sesjami. Przy domyślnym UnsafeMode = false, UseDoconut() dodaje bezpieczeństwo dostępu do dokumentu i host musi skonfigurować sesję ASP.NET:

builder.Services.AddDistributedMemoryCache(); // stan sesji wymaga pamięci podręcznej (MVC/Razor Pages już dodają jedną)
builder.Services.AddSession();
app.UseSession();

Zachowaj DocOptions.IsSecured = true, chyba że przeglądany projekt wymaga inaczej. Nigdy nie używaj UnsafeMode = true jako skrótu migracji. Testuj żądania bez tokenu, z uszkodzonym tokenem, z wygasłym tokenem oraz z tokenem z innej sesji przeglądarki.

Rozproszona aplikacja referencyjna dodaje bilety dostępu i szczegóły transportu. Te API nie są wymagane przy normalnej migracji jednowęzłowej.

Testowanie migracji

Co najmniej, zweryfikuj:

• uruchomienie aplikacji z licencją produkcyjną i każdą zarejestrowaną wtyczką;
• CSS/skrypty Viewer oraz wszystkie żądania obrazów stron w wybranych ścieżkach;
• otwieranie dokumentu, nawigację, przybliżanie, miniatury, drukowanie i wyraźne zamknięcie;
• wyszukiwanie w dokumencie zawierającym tekst oraz stan nieprzeszukiwalności pliku wyłącznie graficznego;
• ładowanie, zapisywanie, eksportowanie adnotacji oraz kontrola możliwości;
• odkrywanie docelowego konwertera, wyjście, pobieranie i stan znaku wodnego;
• strony DICOM, klatki i animacja; metadane techniczne .NET 6 są niedostępne;
• dokumenty chronione hasłem, własne czcionki, tekst niełaciński i skonfigurowane limity czasu;
• odrzucanie tokenów pomiędzy sesjami oraz zachowanie przy wygasłej sesji;
• mobilny, tryb ciemny i ścieżka odwróconego proxy produkcji.

Plan przywrócenia

Zachowaj klasyczny artefakt wdrożeniowy, pasujące pakiety, pliki licencji i skopiowane zasoby przeglądarki razem. Bezpieczne przywrócenie przełącza całą generację aplikacji; nie miesza klasycznego serwera z bieżącymi skryptami ani bieżącego serwera z klasycznymi wywołaniami DocImage.axd.

Przed przełączeniem, udokumentuj:

• slot wdrożeniowy lub artefakt używany do przywrócenia;
• wpływ na bazę danych/pamięć podręczną, jeśli istnieje;
• jak aktywne sesje dokumentów zostaną unieważnione;
• kontrolę zdrowia i dokument testowy używany do podjęcia decyzji o przywróceniu;
• kto może przywrócić poprzedni zestaw pakietów i konfigurację.

Dokumentacja legacy

Przetłumaczona klasyczna instrukcja pozostaje dostępna pod adresem Legacy .NET 6 setup. Nowy Classic integration gateway wyjaśnia te same sygnały identyfikacyjne i odsyła do tego przewodnika migracji.

Zachowaj historyczny URL w zakładkach i zgłoszeniach wsparcia, dopóki klasyczne instalacje nadal istnieją. Dokumentuje on inną generację i nie jest przekierowywany do bieżącego API.