Wprowadzenie do struktury obsługi pakietów

The Package Support Framework to zestaw open source, który ułatwia stosowanie poprawek do istniejącej aplikacji klasycznej (bez modyfikowania kodu), dzięki czemu może działać w kontenerze MSIX. Struktura obsługi pakietów ułatwia aplikacji stosowanie najlepszych rozwiązań nowoczesnego środowiska uruchomieniowego.

Ten artykuł zawiera szczegółowe omówienie poszczególnych składników struktury obsługi pakietów i przewodnik krok po kroku dotyczący korzystania z niego.

Zrozum, co znajduje się w strukturze wsparcia pakietów

Struktura obsługi pakietów zawiera plik wykonywalny, bibliotekę DLL menedżera środowiska uruchomieniowego i zestaw poprawek środowiska uruchomieniowego.

Oto proces:

1. Utwórz plik konfiguracji, który określa poprawki, które chcesz zastosować do aplikacji.
2. Zmodyfikuj pakiet, aby wskazywał plik wykonywalny programu Package Support Framework (PSF).

Gdy użytkownicy uruchamiają aplikację, starter Frameworka Obsługi Pakietów jest pierwszym programem wykonywalnym, który uruchamia się. Odczytuje on plik konfiguracji i wprowadza poprawki środowiska uruchomieniowego oraz bibliotekę DLL menedżera środowiska uruchomieniowego do procesu aplikacji. Menedżer środowiska uruchomieniowego stosuje poprawkę, gdy aplikacja potrzebuje jej do uruchomienia wewnątrz kontenera MSIX.

Krok 1. Identyfikowanie problemów ze zgodnością spakowanych aplikacji

Najpierw utwórz pakiet dla aplikacji. Następnie zainstaluj go, uruchom go i obserwuj jego zachowanie. Mogą pojawić się komunikaty o błędach, które mogą pomóc w zidentyfikowaniu problemu ze zgodnością. Możesz również użyć monitora procesów , aby zidentyfikować problemy. Typowe problemy dotyczą założeń aplikacji dotyczących uprawnień katalogu roboczego i ścieżki programu.

Identyfikowanie problemu przy użyciu monitora procesów

Monitor procesów to zaawansowane narzędzie do obserwowania operacji plików i rejestru aplikacji oraz ich wyników. Może to pomóc w zrozumieniu problemów ze zgodnością aplikacji. Po otwarciu Monitora procesów dodaj filtr (Filtr > Filtr…), aby uwzględnić tylko zdarzenia z pliku wykonywalnego aplikacji.

Zostanie wyświetlona lista zdarzeń. W przypadku wielu z tych zdarzeń słowo SUCCESS pojawi się w kolumnie Wynik .

Opcjonalnie można filtrować zdarzenia, aby wyświetlać tylko błędy.

Jeśli podejrzewasz błąd dostępu do systemu plików, wyszukaj nieudane zdarzenia w obszarze System32/SysWOW64 lub ścieżce plików pakietu. Filtry mogą również pomóc w tym miejscu. Zacznij od dołu tej listy i przewiń w górę. Ostatnio wystąpiły błędy wyświetlane w dolnej części tej listy. Zwróć największą uwagę na błędy zawierające ciągi, takie jak "odmowa dostępu" i "nie znaleziono ścieżki/nazwy", i ignoruj elementy, które nie wyglądają podejrzanie. Plik PSFSample ma dwa problemy. Te problemy można zobaczyć na liście, która zostanie wyświetlona na poniższej ilustracji.

W pierwszym problemie wyświetlanym na tym obrazie aplikacja nie może odczytać pliku "Config.txt", który znajduje się w ścieżce "C:\Windows\SysWOW64". Jest mało prawdopodobne, że aplikacja próbuje odwoływać się bezpośrednio do tej ścieżki. Najprawdopodobniej próbuje odczytać z tego pliku, korzystając ze ścieżki względnej, a domyślnie katalogiem roboczym aplikacji jest "System32/SysWOW64". Sugeruje to, że aplikacja oczekuje, że bieżący katalog roboczy zostanie ustawiony w dowolnym miejscu w pakiecie. Patrząc wewnątrz pliku appx, widzimy, że plik istnieje w tym samym katalogu co plik wykonywalny.

Drugi problem pojawia się na poniższej ilustracji.

W tym problemie aplikacja nie może zapisać pliku .log do ścieżki pakietu. Sugeruje to, że poprawka przekierowania plików może pomóc.

Krok 2. Znajdowanie poprawki środowiska uruchomieniowego

Plik PSF zawiera poprawki środowiska uruchomieniowego, których można teraz używać, takich jak poprawka przekierowania plików.

Poprawka przekierowania plików

Za pomocą poprawki przekierowania plików można przekierowywać próby zapisu lub odczytu danych w katalogu, który nie jest dostępny z poziomu aplikacji działającej w kontenerze MSIX.

Jeśli na przykład aplikacja zapisuje w pliku dziennika, który znajduje się w tym samym katalogu co plik wykonywalny aplikacji, możesz użyć poprawki przekierowania plików , aby utworzyć ten plik dziennika w innej lokalizacji, takiej jak lokalny magazyn danych aplikacji.

Poprawki uruchomieniowe od społeczności

Pamiętaj, aby przejrzeć wkład społeczności na naszej stronie GitHub. Istnieje możliwość, że inni deweloperzy rozwiązali problem podobny do Twojego i udostępnili poprawkę środowiska uruchomieniowego.

Krok 3. Stosowanie poprawki środowiska uruchomieniowego

Możesz zastosować istniejącą poprawkę środowiska uruchomieniowego z kilkoma prostymi narzędziami z zestawu Windows SDK i wykonując następujące kroki.

Przyjrzyjmy się każdemu zadaniu.

Tworzenie folderu układu pakietu

Jeśli masz już plik .msix (lub .appx), możesz rozpakować jego zawartość do folderu układu, który posłuży jako obszar przejściowy dla twojego pakietu. Można to zrobić w wierszu polecenia przy użyciu narzędzia MakeAppx na podstawie ścieżki instalacji zestawu SDK. W tym miejscu znajdziesz narzędzie makeappx.exe na komputerze z systemem Windows 10: x86: C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe x64: C:\Program Files (x86)\Windows Kits\10\bin\x64\makeappx.exe

makeappx unpack /p PSFSamplePackage_1.0.60.0_AnyCPU_Debug.msix /d PackageContents

Otrzymasz coś, co wygląda następująco.

Jeśli nie masz pliku msix (lub .appx), na początek możesz utworzyć folder pakietu i pliki od podstaw.

Pobieranie plików programu Package Support Framework

Pakiet Nuget PSF można uzyskać przy użyciu autonomicznego narzędzia wiersza polecenia NuGet lub programu Visual Studio.

Pobieranie pakietu przy użyciu narzędzia wiersza polecenia

Zainstaluj narzędzie wiersza polecenia Nuget z tej lokalizacji: https://www.nuget.org/downloads. Następnie z wiersza polecenia Nuget uruchom następujące polecenie:

nuget install Microsoft.PackageSupportFramework

Alternatywnie możesz zmienić nazwę rozszerzenia pakietu na .zip i rozpakuj je. Wszystkie potrzebne pliki będą znajdować się w folderze /bin.

Pobieranie pakietu przy użyciu programu Visual Studio

W programie Visual Studio kliknij prawym przyciskiem myszy węzeł rozwiązania lub projektu i wybierz jedno z poleceń Zarządzaj pakietami Nuget. Wyszukaj Microsoft.PackageSupportFramework lub PSF, aby znaleźć pakiet na Nuget.org. Następnie zainstaluj go.

Dodaj pliki Frameworku wsparcia pakietów do pakietu

Dodaj wymagane 32-bitowe i 64-bitowe biblioteki DLL PSF i pliki wykonywalne do katalogu pakietów. Skorzystaj z poniższej tabeli jako przewodnika. Należy również uwzględnić wszystkie potrzebne poprawki środowiska uruchomieniowego. W naszym przykładzie potrzebujemy poprawki przekierowania plików w środowisku uruchomieniowym.

Zawartość pakietu powinna teraz wyglądać mniej więcej tak.

Modyfikowanie manifestu pakietu

Otwórz manifest pakietu w edytorze tekstów, a następnie ustaw Executable atrybut Application elementu na nazwę pliku wykonywalnego programu PSF Launcher. Jeśli znasz architekturę aplikacji docelowej, wybierz odpowiednią wersję, PSFLauncher32.exe lub PSFLauncher64.exe. Jeśli nie, PSFLauncher32.exe będzie działać we wszystkich przypadkach. Oto przykład.

<Package ...>
  ...
  <Applications>
    <Application Id="PSFSample"
                 Executable="PSFLauncher32.exe"
                 EntryPoint="Windows.FullTrustApplication">
      ...
    </Application>
  </Applications>
</Package>

Tworzenie pliku konfiguracji

Utwórz nazwę config.jsonpliku i zapisz ten plik w folderze głównym pakietu. Zmodyfikuj zadeklarowany identyfikator aplikacji pliku config.json, aby wskazać właśnie zamieniony plik wykonywalny. Korzystając z wiedzy uzyskanej podczas używania Process Monitor, można również ustawić katalog roboczy oraz użyć poprawki przekierowania plików, aby przekierować odczyty/zapisy do plików .log w katalogu "PSFSampleApp" powiązanym z pakietem.

{
    "applications": [
        {
            "id": "PSFSample",
            "executable": "PSFSampleApp/PSFSample.exe",
            "workingDirectory": "PSFSampleApp/"
        }
    ],
    "processes": [
        {
            "executable": "PSFSample",
            "fixups": [
                {
                    "dll": "FileRedirectionFixup.dll",
                    "config": {
                        "redirectedPaths": {
                            "packageRelative": [
                                {
                                    "base": "PSFSampleApp/",
                                    "patterns": [
                                        ".*\\.log"
                                    ]
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

Poniżej przedstawiono przewodnik dotyczący schematu config.json:

Klucze applications, processesi fixups są tablicami. Oznacza to, że można użyć pliku config.json do określenia więcej niż jednej aplikacji, procesu i poprawki DLL.

Pakowanie i testowanie aplikacji

Następnie utwórz pakiet.

makeappx pack /d PackageContents /p PSFSamplePackageFixup.msix

Następnie podpisz go.

signtool sign /a /v /fd sha256 /f ExportedSigningCertificate.pfx PSFSamplePackageFixup.msix

Aby uzyskać więcej informacji, zobacz jak utworzyć certyfikat podpisywania pakietu i jak podpisać pakiet przy użyciu narzędzia signtool

Za pomocą programu PowerShell zainstaluj pakiet.

powershell Add-AppPackage .\PSFSamplePackageFixup.msix

Uruchom aplikację i obserwuj zachowanie zastosowanej poprawki środowiska uruchomieniowego. W razie potrzeby powtórz kroki diagnostyki i pakowania.

Sprawdzanie, czy platforma obsługi pakietów jest uruchomiona

Możesz sprawdzić, czy poprawka środowiska uruchomieniowego jest uruchomiona. Aby to zrobić, otwórz Menedżera zadań i kliknij pozycję Więcej szczegółów. Znajdź aplikację, do której zastosowano strukturę obsługi pakietów, i rozwiń szczegóły, aby uzyskać więcej informacji. Powinno być możliwe wyświetlenie, że platforma obsługi pakietów jest uruchomiona.

Korzystanie z Trace Fixup

Alternatywną techniką diagnozowania problemów ze zgodnością z pakietowymi aplikacjami jest użycie Trace Fixup. Ta biblioteka DLL jest dołączona do programu PSF i udostępnia szczegółowy widok diagnostyczny zachowania aplikacji, podobnie jak w przypadku monitora procesów. Jest ona specjalnie zaprojektowana w celu ujawnienia problemów ze zgodnością aplikacji. Aby skorzystać z funkcji Trace Fixup, dodaj bibliotekę DLL do pakietu, dodaj poniższy fragment do sekcji config.json, a następnie spakuj i zainstaluj aplikację.

{
    "dll": "TraceFixup.dll",
    "config": {
        "traceLevels": {
            "filesystem": "allFailures"
        }
    }
}

Domyślnie Trace Fixup filtruje błędy, które mogą być uważane za "oczekiwane". Na przykład aplikacje mogą próbować bezwarunkowo usunąć plik bez sprawdzania, czy już istnieje, ignorując wynik. Ma to niefortunne konsekwencje, że niektóre nieoczekiwane błędy mogą zostać odfiltrowane, więc w powyższym przykładzie wybieramy odbieranie wszystkich błędów z funkcji systemu plików. Robimy to, ponieważ wiemy wcześniej, że próba odczytu z pliku Config.txt kończy się niepowodzeniem z komunikatem "Nie znaleziono pliku". Jest to błąd, który jest często obserwowany i zazwyczaj nie zakłada się, że jest nieoczekiwany. W praktyce najlepszym rozwiązaniem jest rozpoczęcie filtrowania tylko w przypadku nieoczekiwanych awarii, a następnie powrót do wszystkich błędów, jeśli nadal nie można zidentyfikować problemu.

Domyślnie wyniki z korekty śledzenia są wysyłane do dołączonego debugera. W tym przykładzie nie będziemy dołączać debugera i zamiast tego użyjemy programu DebugView z narzędzia SysInternals, aby wyświetlić jego dane wyjściowe. Po uruchomieniu aplikacji możemy zobaczyć te same błędy co poprzednio, co spowodowałoby skierowanie nas do tych samych poprawek środowiska uruchomieniowego.

Debugowanie, rozszerzanie lub tworzenie poprawki środowiska uruchomieniowego

Za pomocą programu Visual Studio można debugować poprawkę środowiska uruchomieniowego, rozszerzyć poprawkę środowiska uruchomieniowego lub utworzyć poprawkę od podstaw. Aby odnieść sukces, musisz wykonać te czynności.

Po zakończeniu rozwiązanie będzie wyglądać mniej więcej tak.

Przyjrzyjmy się każdemu projektowi w tym przykładzie.

Aby zapoznać się z kompletnym przykładem zawierającym wszystkie te typy projektów, zobacz PLIK PSFSample.

Przyjrzyjmy się krokom tworzenia i konfigurowania każdego z tych projektów w rozwiązaniu.

Tworzenie rozwiązania pakietu

Jeśli nie masz jeszcze rozwiązania dla aplikacji komputerowej, utwórz nowe Puste Rozwiązanie w programie Visual Studio.

Możesz również dodać wszystkie posiadane projekty aplikacji.

Dodaj projekt opakowania

Jeśli nie masz jeszcze projektu tworzenia pakietów aplikacji systemu Windows, utwórz go i dodaj go do rozwiązania.

Aby uzyskać więcej informacji na temat projektu tworzenia pakietów aplikacji systemu Windows, zobacz Pakowanie aplikacji przy użyciu programu Visual Studio.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt pakowania, wybierz polecenie Edytuj, a następnie dodaj go do dołu pliku projektu:

<Target Name="PSFRemoveSourceProject" AfterTargets="ExpandProjectReferences" BeforeTargets="_ConvertItems">
<ItemGroup>
  <FilteredNonWapProjProjectOutput Include="@(_FilteredNonWapProjProjectOutput)">
  <SourceProject Condition="'%(_FilteredNonWapProjProjectOutput.SourceProject)'=='<your runtime fix project name goes here>'" />
  </FilteredNonWapProjProjectOutput>
  <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
  <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
</ItemGroup>
</Target>

Dodawanie projektu dla poprawki środowiska uruchomieniowego

Dodaj projekt bibliotekiDynamic-Link języka C++ (DLL) do rozwiązania.

Kliknij prawym przyciskiem myszy ten projekt, a następnie wybierz polecenie Właściwości.

Na stronach właściwości znajdź pole C++ Language Standard, a następnie na liście rozwijanej obok tego pola wybierz opcję ISO C++17 Standard (/std:c++17).

Kliknij prawym przyciskiem myszy ten projekt, a następnie w menu kontekstowym wybierz opcję Zarządzaj pakietami Nuget . Upewnij się, że opcja Źródło pakietu jest ustawiona na Wszystkie lub nuget.org.

Kliknij ikonę ustawień obok tego pola.

Wyszukaj pakiet NuGet PSF*, a następnie zainstaluj go dla tego projektu.

Jeśli chcesz debugować lub rozszerzać istniejącą poprawkę środowiska uruchomieniowego, dodaj pliki poprawki środowiska uruchomieniowego uzyskane za pomocą wskazówek opisanych w sekcji Znajdowanie poprawki środowiska uruchomieniowego w tym przewodniku.

Jeśli zamierzasz utworzyć zupełnie nową poprawkę, nie dodawaj jeszcze niczego do tego projektu. Pomożemy Ci dodać odpowiednie pliki do tego projektu w dalszej części tego przewodnika. Na razie będziemy kontynuować konfigurowanie rozwiązania.

Dodaj projekt, który uruchamia plik wykonywalny PSF Launcher

Dodaj projekt C++ Pusty Projekt do rozwiązania.

Dodaj pakiet Nuget psF do tego projektu, korzystając z tych samych wskazówek opisanych w poprzedniej sekcji.

Otwórz strony właściwości projektu, a na stronie Ustawienia ogólne ustaw właściwość Nazwa docelowa na PSFLauncher32 lub PSFLauncher64 w zależności od architektury aplikacji.

Dodaj odwołanie do projektu poprawki środowiska uruchomieniowego w rozwiązaniu.

Kliknij prawym przyciskiem myszy odwołanie, a następnie w oknie Właściwości zastosuj te wartości.

Skonfiguruj projekt pakowania

W projekcie pakowania kliknij prawym przyciskiem myszy folder Aplikacje , a następnie wybierz polecenie Dodaj odwołanie.

Wybierz projekt PSF Launcher i projekt aplikacji komputerowej, a następnie wybierz przycisk OK.

W węźle Aplikacje kliknij prawym przyciskiem myszy aplikację PSF Launcher, a następnie wybierz polecenie Ustaw jako punkt wejścia.

Dodaj plik o nazwie config.json do projektu pakowania, a następnie skopiuj i wklej następujący tekst json do pliku. Ustaw właściwość Akcja pakietu na Zawartość.

{
    "applications": [
        {
            "id": "",
            "executable": "",
            "workingDirectory": ""
        }
    ],
    "processes": [
        {
            "executable": "",
            "fixups": [
                {
                    "dll": "",
                    "config": {
                    }
                }
            ]
        }
    ]
}

Podaj wartość dla każdego klucza. Użyj tej tabeli jako przewodnika.

Po zakończeniu plik config.json będzie wyglądać mniej więcej tak.

{
  "applications": [
    {
      "id": "DesktopApplication",
      "executable": "DesktopApplication/WinFormsDesktopApplication.exe",
      "workingDirectory": "WinFormsDesktopApplication"
    }
  ],
  "processes": [
    {
      "executable": ".*App.*",
      "fixups": [ { "dll": "RuntimeFix.dll" } ]
    }
  ]
}

Debugowanie poprawki środowiska uruchomieniowego

W programie Visual Studio naciśnij F5, aby uruchomić debuger. Pierwszą rzeczą uruchamianą jest aplikacja PSF Launcher, która z kolei uruchamia docelową aplikację desktopową. Aby debugować docelową aplikację klasyczną, musisz ręcznie dołączyć do procesu aplikacji klasycznej, wybierając pozycję Debugowanie dołączania> do procesu, a następnie wybierając proces aplikacji. Aby zezwolić na debugowanie aplikacji .NET przy użyciu natywnej poprawki biblioteki DLL środowiska uruchomieniowego, wybierz typy kodu zarządzanego i natywnego (debugowanie w trybie mieszanym).

Po skonfigurowaniu tego ustawienia można ustawić punkty przerwania obok wierszy kodu w kodzie aplikacji klasycznej i projekcie poprawki środowiska uruchomieniowego. Jeśli nie masz kodu źródłowego do aplikacji, możesz ustawić punkty przerwania tylko obok wierszy kodu w projekcie poprawki środowiska uruchomieniowego.

Ponieważ debugowanie F5 uruchamia aplikację, wdrażając luźne pliki ze ścieżki folderu układu pakietu, zamiast instalować z pakietu msix/.appx, folder układu zwykle nie ma tych samych ograniczeń zabezpieczeń co zainstalowany folder pakietu. W związku z tym może nie być możliwe odtworzenie błędów odmowy dostępu ścieżki pakietu przed zastosowaniem poprawki środowiska uruchomieniowego.

Aby rozwiązać ten problem, użyj wdrożenia pakietu .msix / .appx zamiast wdrożenia luźnego pliku F5. Aby utworzyć plik pakietu msix/.appx, użyj narzędzia MakeAppx z zestawu Windows SDK, zgodnie z powyższym opisem. Ewentualnie w programie Visual Studio kliknij prawym przyciskiem myszy węzeł projektu aplikacji i wybierz pozycję Sklep —> Utwórz pakiety aplikacji.

Innym problemem z programem Visual Studio jest to, że nie ma wbudowanej obsługi dołączania do żadnych procesów podrzędnych uruchamianych przez debuger. Utrudnia to debugowanie logiki w ścieżce uruchamiania aplikacji docelowej, która musi być ręcznie dołączona przez program Visual Studio po uruchomieniu.

Aby rozwiązać ten problem, użyj debugera obsługującego dołączanie procesów podrzędnych. Należy pamiętać, że zazwyczaj nie można dołączyć debugera just in time (JIT) do aplikacji docelowej. Dzieje się tak, ponieważ większość technik JIT obejmuje uruchomienie debugera zamiast aplikacji docelowej za pośrednictwem klucza rejestru ImageFileExecutionOptions. Powoduje to pokonanie mechanizmu objazdowego używanego przez PSFLauncher.exe do wstrzykiwania FixupRuntime.dll do aplikacji docelowej. WinDbg, dołączony do narzędzi debugowania dla systemu Windows i uzyskany z zestawu Windows SDK, obsługuje dołączanie procesów podrzędnych. Teraz obsługuje również bezpośrednie uruchamianie i debugowanie aplikacji platformy UWP.

Aby debugować uruchamianie aplikacji docelowej jako proces podrzędny, uruchom polecenie WinDbg.

windbg.exe -plmPackage PSFSampleWithFixup_1.0.59.0_x86__7s220nvg1hg3m -plmApp PSFSample

Po wyświetleniu monitu WinDbg włącz debugowanie podrzędne i ustaw odpowiednie punkty przerwania.

.childdbg 1
g

(wykonaj polecenie, aż aplikacja docelowa zostanie uruchomiona i przejdzie do trybu debugowania)

sxe ld fixup.dll
g

(wykonaj aż do momentu załadowania poprawkowej biblioteki DLL)

bp ...

Wsparcie

Masz pytania? Zapytaj nas na przestrzeni konwersacyjnej Package Support Framework na stronie społeczności technicznej MSIX.