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 przed zmianą pakietów, uruchomieniem, licencjami lub zasobami przeglądarki należy zidentyfikować generację na podstawie API w aplikacji.

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

Jeśli obie kolumny pojawiają się w tej samej aplikacji, traktuj migrację jako niekompletną. Nie wysyłaj 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 blokady lub buforowany .nupkg nie identyfikuje więc samego API hostującego. Zanotuj dokładną wersję pakietu i sprawdź razem Program.cs, konstrukcję viewer, otwieranie dokumentów oraz skrypty przeglądarki.

Obecne wydanie, które zostało zweryfikowane w tym przewodniku, to Doconut.NET6 26.7.0. 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 możliwą do wdrożenia kopię zapasową istniejącej aplikacji.
2. Zanotuj dokładne wersje pakietu podstawowego i wtyczek.
3. Spisz wszystkie mapowania DocImage.axd, wywołania new Viewer(...), wywołania ładowania licencji, skopiowane skrypty Doconut, niestandardowe akcje paska narzędzi oraz endpointy otwierania dokumentów.
4. Zachowaj bieżące pliki .lic oraz tajemnice 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 ustawienia limitu czasu sesji, zachowania bezpieczeństwa, 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 instaluje najnowsze stabilne wydanie:

dotnet add package Doconut.NET6

Aby uzyskać powtarzalną migrację do wydania zweryfikowanego 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 następującego priorytetu:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatyczne wykrywanie szuka plików Doconut.Viewer.lic oraz powiązanych Doconut.Viewer.<Capability>.lic. Klasyczne wywołanie Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...) nie jest obecnym 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 z zależnościami pamięci podręcznej ASP.NET i dostępem do żądania:

var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

Viewer jest usługą przejściową. Menedżer sesji dokumentu i jego pamięć podręczna posiadają długotrwale utrzymany stan dokumentu, a nie konkretną wstrzykniętą instancję Viewer.

Middleware i routing zasobów

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

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 zabezpieczenia sesji są włączone;
2. wywołaj UseDoconutResources() przed UseDoconut();
3. utrzymaj ResourcesPath, generowane adresy URL zasobów oraz ResPath po stronie klienta w zgodzie;
4. przy mapowaniu UseDoconut() do gałęzi, utrzymaj tę gałąź i BasePath po stronie klienta w zgodzie.

MiddlewarePath jest zweryfikowaną konfiguracją; nie tworzy 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.

Konstrukcja i cykl życia Viewer

Usuń pamięci podręczne Viewer zarządzane przez aplikację. Wstrzyknij Viewer do punktu końcowego, strony Razor, kontrolera lub usługi o zasięgu aplikacji:

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 synchroniczne OpenDocument(...) metodą OpenDocumentAsync(...):

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 wyraźnie, gdy przeglądarka już jej nie potrzebuje:

viewer.CloseDocument(token);

Nie używaj ponownie klasycznego tokenu po migracji. Otwieraj każdy dokument ponownie poprzez bieżące API.

Klasy konfiguracyjne

Obecne API rozdziela obszary odpowiedzialności:

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

Pasek narzędzi Viewer, Search i Annotation

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 zarządzany przez aplikację;
3. renderuj searchBarMount, annBarMount oraz wymagany montaż Viewer;
4. generuj skrypty Viewer i licencjonowane moduły przy użyciu ReferenceScripts;
5. załaduj własny plik viewerToolbar.js aplikacji;
6. zainicjuj jednego 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, jako zasoby zależne od możliwości.

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 generowanymi przez ReferenceCss i ReferenceScripts.

Rejestracja wtyczek

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() waliduje zarejestrowane możliwości wtyczek podczas uruchamiania. 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 zabezpieczenie dostępu do dokumentu i host musi skonfigurować sesję ASP.NET:

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

Utrzymuj 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 przeglądarki oraz wszystkie żądania obrazów stron w wybranych ścieżkach;
• otwieranie dokumentu, nawigację, przybliżenie, 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 celu konwertera, wyjście, pobieranie i stan znaku wodnego;
• strony DICOM, klatki i animacje; 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 między sesjami oraz zachowanie przy wygasłej sesji;
• mobilny, tryb ciemny i ścieżka odwróconego proxy produkcji.

Plan przywracania

Zachowaj klasyczny artefakt wdrożeniowy, odpowiadają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 przywracania;
• wpływ na bazę danych/bufor, jeśli istnieje;
• jak aktywne sesje dokumentów będą unieważniane;
• 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 starszych wersji

Przetłumaczony klasyczny podręcznik jest nadal dostępny pod adresem Starsza konfiguracja .NET 6. Nowa Klasyczna brama integracji 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.