Migracja z klasycznej integracji .NET 6

Przenieś istniejącą aplikację Doconut.NET6 do bieżącego DI i asynchronicznego API

Doconut ma dwie odrębne integracje .NET 6. Mogą używać tej samej Doconut.NET6 nazwy pakietu, 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 projekt zawiera…Generacja
app.MapWhen(... "DocImage.axd" ...)Starsza / klasyczna
new Viewer(_cache, _accessor, ...)Starsza / klasyczna
Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...)Starsza / klasyczna
Ręcznie skopiowane docViewer.js, documentLinks.js, lub docViewer.UI.jsStarsza / klasyczna
builder.Services.AddDoconut(...)Bieżąca integracja
app.UseDoconutResources() plus app.UseDoconut()Bieżąca integracja
Viewer dostarczany przez wstrzykiwanie zależnościBieżąca integracja
await viewer.OpenDocumentAsync(...)Bieżąca integracja

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 identyfikuje więc API hostującego samodzielnie. Zanotuj dokładną wersję pakietu i sprawdź Program.cs, konstrukcję viewer, otwieranie dokumentów oraz skrypty przeglądarki razem.

Obecne wydanie audytowane dla tego przewodnika to Doconut.NET6 26.7.0. Jego 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 pakietu podstawowego i wtyczek.
  3. Inwentaryzuj każde mapowanie DocImage.axd, wywołanie new Viewer(...), wywołanie ładowania licencji, skopiowany skrypt Doconut, niestandardową akcję paska narzędzi oraz punkt końcowy otwierania dokumentu.
  4. Zachowaj bieżące pliki .lic i 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, trasowanie żą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:

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.9.0

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

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatyczne wykrywanie szuka Doconut.Viewer.lic i towarzyszących 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 pliki towarzyszące razem przy użyciu automatycznego wykrywania, uruchom ponownie po zmianie licencji i zweryfikuj możliwości przez IDoconutLicenseService.

Nie zakładaj, że obecność starej licencji wtyczki dowodzi uprawnienia 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 pamięcią podręczną ASP.NET oraz zależnościami request-accessor:

csharp
// 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:

csharp
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 posiadają długotrwały stan dokumentu, a nie konkretną wstrzykniętą instancję Viewer.

Middleware i trasowanie zasobów

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

csharp
// 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łąź, zachowaj 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.

Konstrukcja i cykl życia Viewera

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:

csharp
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 rejestruj go, nie przechowuj ani nie umieszczaj w analizach.

Otwieranie i zamykanie dokumentów

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

csharp
// Aktualna integracja .NET 6: Viewer pochodzi z DI i 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:

csharp
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:

ZagadnienieObecny typ
Ścieżki middleware, licencjonowanie, rejestracja wtyczekDoconutOptions
Hasło, limit czasu, bezpieczeństwo, znak wodnyDocOptions
Renderowanie formatu i DPIPdfConfig, WordConfig, ExcelConfig, i inne typy BaseConfig
Domyślne ustawienia widgetu przeglądarkiViewerConfig lub równoważne opcje JavaScript
Wygenerowane CSS i skryptyCssConfig i ScriptConfig

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 Viewera, wyszukiwanie i adnotacje

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

  1. wyemituj CSS Viewera oraz licencjonowany CSS Search/Annotation przy użyciu ReferenceCss;
  2. renderuj pasek narzędzi Viewera należący do aplikacji;
  3. renderuj searchBarMount, annBarMount oraz wymaganą montaż Viewera;
  4. wyemituj skrypty Viewera i licencjonowane moduły 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 Viewera, 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 wyemitowanymi przez ReferenceCss i ReferenceScripts.

Rejestracja wtyczki

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

csharp
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. Z domyślnym UnsafeMode = false, UseDoconut() dodaje bezpieczeństwo dostępu do dokumentu i host musi skonfigurować sesję ASP.NET:

csharp
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 interfejsy 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 i 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 nieprzeszukiwalny pliku tylko z obrazem;
  • ładowanie, zapisywanie, eksportowanie adnotacji oraz kontrola możliwości;
  • odkrywanie celu konwertera, wyjście, pobieranie i stan znaku wodnego;
  • strony, klatki i animacje DICOM; 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, 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 przywracania;
  • wpływ na bazę danych/pamięć podręczną, 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 starsza

Przetłumana klasyczna instrukcja pozostaje dostępna pod adresem Starsza konfiguracja .NET 6. Nowy Brama integracji klasycznej 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.

Czy ta strona była pomocna?