Начало работы с платформой поддержки пакетов

Платформа поддержки пакетов — это пакет с открытым исходным кодом, который помогает применять исправления к существующему классическому приложению (без изменения кода), чтобы он смог выполняться в контейнере MSIX. Платформа поддержки пакетов помогает приложению следовать рекомендациям современной среды выполнения.

В этой статье приведены подробные сведения о каждом компоненте платформы поддержки пакетов и пошаговые инструкции по использованию.

Понять, что входит в структуру поддержки пакетов

Платформа поддержки пакетов содержит исполняемый файл, библиотеку DLL диспетчера среды выполнения и набор исправлений среды выполнения.

Ниже приведен процесс.

1. Создайте файл конфигурации, указывающий исправления, которые необходимо применить к приложению.
2. Измените пакет, чтобы указать исполняемый файл средства поддержки пакетов (PSF).

Когда пользователи запускают приложение, средство запуска платформы поддержки пакетов — это первый исполняемый файл, который запускается. Он считывает файл конфигурации и внедряет исправления среды выполнения и библиотеку DLL диспетчера среды выполнения в процесс приложения. Диспетчер среды выполнения применяет исправление, если оно требуется приложению для запуска внутри контейнера MSIX.

Шаг 1. Определение проблем совместимости упакованных приложений

Сначала создайте пакет для приложения. Затем установите его, запустите его и просмотрите его поведение. Вы можете получать сообщения об ошибках, которые помогут определить проблему совместимости. Вы также можете использовать монитор процессов для выявления проблем. Распространенные проблемы связаны с предположениями приложения о разрешениях рабочего каталога и пути программы.

Использование монитора процессов для выявления проблемы

Монитор процессов — это мощная служебная программа для наблюдения за операциями файла и реестра приложения и их результатов. Это поможет вам понять проблемы совместимости приложений. После открытия монитора процессов добавьте фильтр ( > фильтр...), чтобы включить только события из исполняемого файла приложения.

Появится список событий. Во многих из этих событий слово SUCCESS появится в столбце "Результат ".

При необходимости можно отфильтровать события только для отображения только сбоев.

Если подозревается сбой доступа к файловой системе, выполните поиск событий сбоя, которые находятся в папке System32/SysWOW64 или пути к файлу пакета. Фильтры также могут помочь здесь. Начните в нижней части этого списка и прокрутите вверх. Ошибки, которые отображаются в нижней части этого списка, произошли в последнее время. Обратите внимание на ошибки, содержащие строки, такие как "доступ запрещен", и "путь/имя не найдено", и игнорируйте вещи, которые не выглядят подозрительными. PSFSample имеет две проблемы. Эти проблемы отображаются в списке, который отображается на следующем рисунке.

В первой проблеме, которая отображается на этом изображении, приложение не считывается из файла "Config.txt", расположенного в пути "C:\Windows\SysWOW64". Вряд ли приложение пытается ссылаться на этот путь напрямую. Скорее всего, происходит попытка прочитать из этого файла, используя относительный путь, и по умолчанию "System32/SysWOW64" является рабочим каталогом приложения. Это предполагает, что приложение ожидает, что текущий рабочий каталог будет установлен где-то в программном пакете. Глядя внутри appx, мы видим, что файл существует в том же каталоге, что и исполняемый файл.

Вторая проблема отображается на следующем рисунке.

В этом случае приложению не удается записать файл .log в путь к пакету. Это может предполагать, что корректировка перенаправления файлов может быть полезной.

Шаг 2. Поиск исправления среды выполнения

PSF содержит исправления среды выполнения, которые можно использовать прямо сейчас, например исправление перенаправления файлов.

Исправление перенаправления файлов

Исправление перенаправления файлов можно использовать для перенаправления попыток записи или чтения данных в каталоге, который недоступен из приложения, работающего в контейнере MSIX.

Например, если ваше приложение записывает данные в файл журнала, который находится в том же каталоге, что и исполняемый файл программы, вы можете использовать исправление перенаправления файлов для создания этого файла журнала в другом месте, например, в локальном хранилище данных приложения.

Исправления в процессе выполнения от сообщества

Обязательно просмотрите вклад сообщества на страницу GitHub . Возможно, что другие разработчики устранили проблему, аналогичную вашей, и предоставили общий доступ к исправлению среды выполнения.

Шаг 3. Применение исправления среды выполнения

Вы можете применить существующее исправление среды выполнения с несколькими простыми инструментами из пакета SDK для Windows и выполните следующие действия.

Давайте рассмотрим каждую задачу.

Создание папки макета пакета

Если у вас уже есть файл .msix (или .appx), его содержимое можно распаковать в папку с макетом, которая будет служить зоной подготовки вашего пакета. Это можно сделать из командной строки с помощью средства MakeAppx на основе пути установки пакета SDK, в котором вы найдете средство makeappx.exe на компьютере с 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

Это даст вам что-то, что выглядит следующим образом.

Если у вас нет MSIX-файла (или .appx), можно создать папку и файлы пакета с нуля.

Получите файлы платформы поддержки пакетов

Пакет Nuget PSF можно получить с помощью автономного средства командной строки Nuget или Visual Studio.

Получение пакета с помощью средства командной строки

Установите средство командной строки Nuget из этого местоположения: https://www.nuget.org/downloads Затем в командной строке Nuget выполните следующую команду:

nuget install Microsoft.PackageSupportFramework

Кроме того, можно переименовать расширение пакета в .zip и распакуйте его. Все необходимые файлы будут находиться в папке /bin.

Получение пакета с помощью Visual Studio

В Visual Studio щелкните правой кнопкой мыши узел решения или проекта и выберите одну из команд управления пакетами Nuget. Найдите пакет Microsoft.PackageSupportFramework или PSF , чтобы найти пакет в Nuget.org. Затем установите его.

Добавление файлов платформы поддержки пакетов в пакет

Добавьте необходимые 32-разрядные и 64-разрядные библиотеки DLL PSF и исполняемые файлы в каталог пакетов. Используйте следующую таблицу в качестве руководства. Вам также следует включить любые исправления на этапе выполнения, которые вам нужны. В нашем примере нам нужно исправление перенаправления файлов во время выполнения.

Содержимое пакета должно выглядеть примерно так.

Изменение манифеста пакета

Откройте манифест пакета в текстовом редакторе, а затем установите атрибут Executable элемента Application на имя исполняемого файла средства запуска PSF. Если вы знаете архитектуру целевого приложения, выберите соответствующую версию, PSFLauncher32.exe или PSFLauncher64.exe. В противном случае PSFLauncher32.exe будет работать во всех случаях. Вот пример.

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

Создание файла конфигурации

Создайте имя config.jsonфайла и сохраните этот файл в корневую папку пакета. Измените объявленный идентификатор приложения файла config.json, чтобы указать исполняемый файл, который вы только что заменили. Используя знания, полученные с помощью Process Monitor, вы также можете задать рабочий каталог и использовать исправление перенаправления файлов для перенаправления операций чтения и записи в файлы с расширением .log в каталоге "PSFSampleApp", относительном к пакету.

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

Ниже приведено руководство по схеме config.json:

Ключи applications, processes и fixups являются массивами. Это означает, что файл config.json можно использовать для указания нескольких приложений, процессов и библиотеки DLL исправления.

Упаковка и тестирование приложения

Затем создайте пакет.

makeappx pack /d PackageContents /p PSFSamplePackageFixup.msix

Затем подпишите его.

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

Дополнительные сведения см. в статье о создании сертификата подписи пакета и о том, как подписать пакет с помощью средства подписи

С помощью PowerShell установите пакет.

powershell Add-AppPackage .\PSFSamplePackageFixup.msix

Запустите приложение и просмотрите поведение с примененным исправлением среды выполнения. Повторите шаги диагностики и упаковки по мере необходимости.

Проверьте, запущена ли платформа поддержки пакетов

Вы можете проверить, выполняется ли исправление среды выполнения. Это можно сделать, чтобы открыть диспетчер задач и нажать кнопку "Дополнительные сведения". Найдите приложение, к которому была применена платформа поддержки пакетов, и разверните подробные сведения о приложении, чтобы получить дополнительные сведения. Вы должны увидеть, что платформа поддержки пакетов запущена.

Используйте исправление трассировки

Альтернативным способом диагностики проблем совместимости упакованных приложений является использование средства исправления трассировки. Эта библиотека DLL включается в PSF и предоставляет подробное диагностическое представление о поведении приложения, аналогичном монитору процессов. Он специально предназначен для выявления проблем совместимости приложений. Чтобы использовать Trace Fixup, добавьте библиотеку DLL в пакет, добавьте следующий фрагмент в config.json, а затем упакуйте и установите ваше приложение.

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

По умолчанию средство исправления трассировки фильтрует сбои, которые могут считаться ожидаемыми. Например, приложения могут пытаться безоговорочно удалить файл, не проверяя наличие файла, игнорируя результат. К сожалению, это может привести к тому, что некоторые непредвиденные сбои могут быть исключены, поэтому в приведенном выше примере мы предпочли получать все сбои из функций файловой системы. Это связано с тем, что мы знаем, что попытка чтения из файла Config.txt завершается ошибкой с сообщением "файл не найден". Это сбой, который часто наблюдается, и обычно не предполагается, что это непредвиденное. На практике, скорее всего, лучше начать фильтрацию только по непредвиденным сбоям, а затем вернуться ко всем сбоям, если возникла проблема, которая по-прежнему не может быть идентифицирована.

По умолчанию выходные данные из средства исправления трассировки отправляются в подключенный отладчик. В этом примере мы не будем присоединять отладчик и вместо этого будем использовать программу DebugView из SysInternals для просмотра выходных данных. После запуска приложения можно увидеть те же сбои, что и раньше, что указывает нам на те же исправления среды выполнения.

Отладить, расширить или создать исправление для исполняемой среды

Visual Studio можно использовать для отладки исправления среды выполнения, расширения исправления среды выполнения или создания из нуля. Чтобы добиться успеха, вам нужно сделать следующее.

Когда вы закончите, решение будет выглядеть примерно так.

Рассмотрим каждый проект в этом примере.

Полный пример, содержащий все эти типы проектов, см. в разделе PSFSample.

Давайте рассмотрим шаги по созданию и настройке каждого из этих проектов в решении.

Создать пакетное решение

Если у вас еще нет решения для настольного приложения, создайте в Visual Studio новое Blank Solution.

Вы также можете добавить все проекты приложений, которые у вас есть.

Добавление проекта упаковки

Если у вас еще нет проекта упаковки приложений Windows, создайте его и добавьте его в решение.

Дополнительные сведения о проекте упаковки приложений Windows см. в статье "Упаковка приложения" с помощью Visual Studio.

В обозревателе решений щелкните правой кнопкой мыши проект упаковки, выберите "Изменить", а затем добавьте его в нижней части файла проекта:

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

Добавление проекта для исправления времени выполнения

Добавьте проект библиотекиDynamic-Link C++ (DLL) в решение.

Щелкните правой кнопкой мыши этот проект и выберите пункт "Свойства".

На страницах свойств найдите поле "Стандартный язык C++", а затем в раскрывающемся списке рядом с этим полем выберите параметр ISO C++17 Standard (/std:c++17).

Щелкните правой кнопкой мыши этот проект, а затем в контекстном меню выберите параметр "Управление пакетами Nuget ". Убедитесь, что для параметра источника пакета задано значение All или nuget.org.

Щелкните значок параметров рядом с этим полем.

Найдите пакет Nuget PSF* и установите его для этого проекта.

Если вы хотите выполнить отладку или расширение существующего исправления среды выполнения, добавьте файлы исправления среды выполнения, полученные с помощью инструкций, описанных в разделе "Поиск среды выполнения " этого руководства.

Если вы планируете создать новое исправление, не добавляйте ничего в этот проект. Мы поможем добавить нужные файлы в этот проект далее в этом руководстве. Теперь мы продолжим настройку решения.

Добавьте проект, запускающий исполняемый файл загрузчика PSF

Добавьте в решение проект C++ Empty Project.

Добавьте пакет Nuget PSF в этот проект, используя те же инструкции, которые описаны в предыдущем разделе.

Откройте страницы свойств проекта и на странице "Общие параметры" задайте для свойства Target Name значение PSFLauncher32 или PSFLauncher64 в зависимости от архитектуры приложения.

Добавьте ссылку на проект по исправлению среды выполнения в решении.

Щелкните правой кнопкой мыши ссылку, а затем в окне свойств примените эти значения.

Настройка проекта упаковки

В проекте упаковки щелкните правой кнопкой мыши папку "Приложения " и выберите команду "Добавить ссылку".

Выберите проект средства запуска PSF и проект настольного приложения, а затем нажмите кнопку «ОК».

На узле Приложения нажмите правой кнопкой мыши по приложению PSF Launcher и выберите Задать в качестве точки входа.

Добавьте файл с именем config.json в проект упаковки, а затем скопируйте и вставьте следующий текст JSON в файл. Задайте для свойства "Действие пакета " значение Content.

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

Укажите значение для каждого ключа. Используйте эту таблицу в качестве справочника.

По завершении файл config.json будет выглядеть примерно так.

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

Отладка исправления среды выполнения

В Visual Studio нажмите клавишу F5, чтобы запустить отладчик. Первое, что запускается, — это приложение средства запуска PSF, которое, в свою очередь, запускает ваше целевое настольное приложение. Чтобы выполнить отладку целевого настольного приложения, необходимо вручную подключиться к процессу настольного приложения, выбрав Отладка -> Подключиться к процессу, и затем выберите процесс приложения. Чтобы разрешить отладку приложения .NET с использованием исправляющей DLL для нативной среды выполнения, выберите управляемые и нативные типы кода (отладка в смешанном режиме).

После настройки этого можно задать точки останова рядом со строками кода в коде настольного приложения и проекте исправления среды выполнения. Если в приложении нет исходного кода, вы сможете задать точки останова только рядом со строками кода в проекте исправления среды выполнения.

Так как отладка F5 запускает приложение путем развертывания свободных файлов из пути к папке макета пакета, а не установки из пакета MSIX/.appx, папка макета обычно не имеет одинаковых ограничений безопасности, что и установленная папка пакета. В результате может быть невозможно воспроизвести ошибки отказа доступа к пути пакета перед применением исправления среды выполнения.

Чтобы устранить эту проблему, используйте развертывание пакета .msix/.appx вместо развертывания одиночных файлов через F5. Чтобы создать файл пакета MSIX/.appx, используйте служебную программу MakeAppx из пакета SDK для Windows, как описано выше. Кроме того, в Visual Studio щелкните правой кнопкой мыши узел проекта приложения и выберите Store —> создать пакеты приложений.

Другая проблема с Visual Studio заключается в том, что она не поддерживает встроенное подключение к дочерним процессам, запущенным отладчиком. Это затрудняет отладку логики на этапе запуска целевого приложения, которое должно быть вручную подключено в Visual Studio после запуска.

Чтобы устранить эту проблему, используйте инструмент для отладки, поддерживающий присоединение дочернего процесса. Обратите внимание, что обычно невозможно подключить JIT-отладчик к целевому приложению. Это связано с тем, что большинство методов JIT включают запуск отладчика вместо целевого приложения с помощью раздела реестра ImageFileExecutionOptions. Это нейтрализует обходной механизм, используемый PSFLauncher.exe для внедрения FixupRuntime.dll в целевое приложение. WinDbg, включенный в средства отладки для Windows и полученный из пакета SDK для Windows, поддерживает присоединение дочернего процесса. Она также теперь поддерживает непосредственное запуск и отладку приложения UWP.

Чтобы выполнить отладку целевого приложения, запускаемого в качестве дочернего процесса, запустите WinDbg.

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

В командной строке WinDbg включите дочернюю отладку и задайте соответствующие точки останова.

.childdbg 1
g

(выполняется до запуска целевого приложения и разрывается в отладчике)

sxe ld fixup.dll
g

(выполнять до тех пор, пока не загрузится исправляющая библиотека DLL)

bp ...

Поддержка

У вас есть вопросы? Обратитесь к нам в разделе Package Support Framework на сайте технического сообщества MSIX.