Начало работы с платформой поддержки пакетов
Платформа поддержки пакетов — это пакет открытый код, который помогает применять исправления к существующему классическому приложению (без изменения кода), чтобы он смог выполняться в контейнере MSIX. Платформа поддержки пакетов помогает настроить приложения в соответствии с требованиями современных сред выполнения.
В этой статье представлен обзор каждого компонента платформы поддержки пакетов и пошаговое руководство по его использованию.
Общие сведения о том, что находится в платформе поддержки пакетов
Платформа поддержки пакетов содержит исполняемый файл, библиотеку DLL диспетчера среды выполнения и набор исправлений среды выполнения.
Ниже приведен процесс.
- Создайте файл конфигурации, указывающий исправления, которые необходимо применить к приложению.
- Измените пакет, чтобы он указывал на исполняемый файл средства запуска платформы поддержки пакетов (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 и исполняемые файлы в каталог пакета. Руководствуйтесь следующей таблицей. Вы также хотите включить все необходимые исправления среды выполнения. В нашем примере нам нужен исправление среды выполнения перенаправления файлов.
Исполняемый файл приложения — x64 | Исполняемый файл приложения — x86 |
---|---|
PSFLauncher64.exe | PSFLauncher32.exe |
PSFRuntime64.dll | PSFRuntime32.dll |
PSFRunDll64.exe | PSFRunDll32.exe |
Содержимое пакета должно выглядеть примерно так.
Изменение манифеста пакета
Откройте манифест пакета в текстовом редакторе, а затем задайте 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, чтобы он указывал на только что замененный исполняемый файл. Используя знания, полученные при использовании монитора процессов, можно также задать рабочий каталог, а также использовать исправление перенаправления файлов для перенаправления операций чтения и записи в 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:
Array | ключ | Значение |
---|---|---|
веб-масштабированием; | идентификатор | Используйте значение Id атрибута Application элемента в манифесте пакета. |
веб-масштабированием; | исполняемый файл | Относительный путь к исполняемому файлу, который требуется запустить. В большинстве случаев это значение можно получить из файла манифеста пакета перед изменением. Это значение Executable атрибута Application элемента. |
веб-масштабированием; | WorkingDirectory | (Необязательно) Относительный путь к пакету, используемый в качестве рабочего каталога запуска приложения. Если это значение не задано, операционная система использует System32 каталог в качестве рабочего каталога приложения. |
процессы | исполняемый файл | В большинстве случаев это будет имя настроенного executable выше пути и расширения файла. |
Исправлений | Файл DLL. | Относительный путь к исправлению msix/.appx для загрузки. |
Исправлений | config | (Необязательно) Управляет поведением библиотеки DLL исправления. Точный формат этого значения зависит от исправления по исправлению, так как каждое исправление может интерпретировать этот "большой двоичный объект" по мере необходимости. |
processes
, applications
и 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 и предоставляет подробное диагностическое представление о поведении приложения, аналогично монитору процессов. Он специально разработан для выявления проблем совместимости приложений. Чтобы использовать исправление трассировки, добавьте библиотеку DLL в пакет, добавьте следующий фрагмент в файл config.json, а затем пакет и установите приложение.
{
"dll": "TraceFixup.dll",
"config": {
"traceLevels": {
"filesystem": "allFailures"
}
}
}
По умолчанию исправление трассировки фильтрует сбои, которые могут считаться ожидаемыми. Например, приложения могут попытаться безоговорочно удалить файл, не проверяя, существует ли он, игнорируя результат. Это приводит к сожалению, что некоторые непредвиденные сбои могут быть отфильтрованы, поэтому в приведенном выше примере мы решили получить все сбои из функций файловой системы. Это происходит потому, что мы знаем, что попытка чтения из файла Config.txt завершается ошибкой с сообщением "файл не найден". Это сбой, который часто наблюдается и обычно не предполагается непредвиденным. На практике, скорее всего, лучше начать фильтрацию только по непредвиденным сбоям, а затем вернуться ко всем сбоям, если есть проблема, которая по-прежнему не может быть выявлена.
По умолчанию выходные данные исправления трассировки отправляются в подключенный отладчик. В этом примере мы не собираемся подключить отладчик и вместо этого будем использовать программу DebugView из SysInternals для просмотра выходных данных. После запуска приложения можно увидеть те же сбои, что и раньше, что указывает на те же исправления среды выполнения.
Отладка, расширение или создание исправления среды выполнения
Visual Studio можно использовать для отладки исправления среды выполнения, расширения исправления среды выполнения или создания с нуля. Для успешного выполнения этих действий вам потребуется выполнить эти действия.
- Добавление проекта упаковки
- Добавление проекта для исправления среды выполнения
- Добавление проекта, запускающего исполняемый файл средства запуска PSF
- Настройка проекта упаковки
Когда все будет готово, решение будет выглядеть примерно так.
Рассмотрим каждый проект в этом примере.
Project | Назначение |
---|---|
DesktopApplicationPackage | Этот проект основан на проекте упаковки приложений Windows и выводит пакет MSIX. |
Runtimefix | Это проект библиотеки Dynamic-Linked C++, содержащий одну или несколько функций замены, которые служат исправлением среды выполнения. |
PSFLauncher | Это пустой проект C++. Этот проект — это место для сбора распространяемых файлов среды выполнения платформы поддержки пакетов. Он выводит исполняемый файл. Этот исполняемый файл — это первое, что запускается при запуске решения. |
WinFormsDesktopApplication | Этот проект содержит исходный код классического приложения. |
Полный пример, содержащий все эти типы проектов, см. в разделе PSFSample.
Давайте рассмотрим шаги по созданию и настройке каждого из этих проектов в решении.
Создание решения пакета
Если у вас еще нет решения для классического приложения, создайте новое пустое решение в Visual Studio.
Вы также можете добавить все проекты приложений, которые у вас есть.
Добавление проекта упаковки
Если у вас еще нет проекта упаковки приложений 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>
Добавление проекта для исправления среды выполнения
Добавьте проект библиотеки динамической компоновки (DLL) C++ в решение.
Щелкните проект правой кнопкой мыши и выберите пункт "Свойства".
На страницах свойств найдите поле "Стандартный язык C++", а затем в раскрывающемся списке рядом с этим полем выберите параметр ISO C++17 Standard (/std:c++17).
Щелкните проект правой кнопкой мыши, а затем в контекстном меню выберите пункт "Управление пакетами NuGet ". Убедитесь, что для параметра источника пакета задано значение All или nuget.org.
Щелкните значок параметров рядом с этим полем.
Найдите пакет Nuget PSF* и установите его для этого проекта.
Если вы хотите отладить или расширить существующее исправление среды выполнения, добавьте файлы исправления среды выполнения, полученные с помощью инструкций, описанных в разделе "Поиск исправления среды выполнения " этого руководства.
Если вы планируете создать новое исправление, не добавляйте ничего в этот проект. Далее в этом руководстве мы поможем вам добавить нужные файлы в этот проект. Сейчас мы продолжим настройку решения.
Добавление проекта, запускающего исполняемый файл средства запуска PSF
Добавьте проект пустого проекта C++ в решение.
Добавьте пакет Nuget PSF в этот проект с помощью того же руководства, что и в предыдущем разделе.
Откройте страницы свойств проекта и на странице "Общие параметры" задайте для свойства Target Name значение PSFLauncher32
или PSFLauncher64
в зависимости от архитектуры приложения.
Добавьте ссылку на проект по исправлению среды выполнения в решении.
Щелкните ссылку правой кнопкой мыши, а затем в окне "Свойства" примените эти значения.
Свойство | Значение |
---|---|
Копирование локальной среды | True |
Копировать локальные вспомогательные сборки | True |
Выходные данные ссылочной сборки | True |
Компоновать зависимости библиотек | False |
Входные данные зависимостей библиотеки ссылок | False |
Настройка проекта упаковки
В проекте упаковки щелкните правой кнопкой мыши папку Приложения и выберите Добавить ссылку.
Выберите проект средства запуска PSF и проект классического приложения, а затем нажмите кнопку "ОК ".
Примечание
Если у вас нет исходного кода для приложения, просто выберите проект средства запуска PSF. Мы покажем, как ссылаться на исполняемый файл при создании файла конфигурации.
В узле "Приложения" щелкните правой кнопкой мыши приложение средства запуска PSF и выберите пункт "Задать в качестве точки входа".
Добавьте файл с именем config.json
в проект упаковки, а затем скопируйте и вставьте следующий текст JSON в файл. Задайте для свойства "Действие пакета " значение Content.
{
"applications": [
{
"id": "",
"executable": "",
"workingDirectory": ""
}
],
"processes": [
{
"executable": "",
"fixups": [
{
"dll": "",
"config": {
}
}
]
}
]
}
Укажите значение для каждого ключа. Используйте эту таблицу в качестве справочника.
Array | ключ | Значение |
---|---|---|
веб-масштабированием; | идентификатор | Используйте значение Id атрибута Application элемента в манифесте пакета. |
веб-масштабированием; | исполняемый файл | Относительный путь к исполняемому файлу, который требуется запустить. В большинстве случаев это значение можно получить из файла манифеста пакета перед изменением. Это значение Executable атрибута Application элемента. |
веб-масштабированием; | WorkingDirectory | (Необязательно) Относительный путь к пакету, используемый в качестве рабочего каталога запуска приложения. Если это значение не задано, операционная система использует System32 каталог в качестве рабочего каталога приложения. |
процессы | исполняемый файл | В большинстве случаев это будет имя настроенного executable выше пути и расширения файла. |
Исправлений | Файл DLL. | Относительный путь к загружаемой библиотеке DLL исправления. |
Исправлений | config | (Необязательно) Управляет поведением библиотеки DLL исправления. Точный формат этого значения зависит от исправления по исправлению, так как каждое исправление может интерпретировать этот "большой двоичный объект" по мере необходимости. |
По завершении config.json
файл будет выглядеть примерно так.
{
"applications": [
{
"id": "DesktopApplication",
"executable": "DesktopApplication/WinFormsDesktopApplication.exe",
"workingDirectory": "WinFormsDesktopApplication"
}
],
"processes": [
{
"executable": ".*App.*",
"fixups": [ { "dll": "RuntimeFix.dll" } ]
}
]
}
Примечание
processes
, applications
и fixups
ключи являются массивами. Это означает, что файл config.json можно использовать для указания нескольких приложений, процессов и исправлений DLL.
Отладка исправления среды выполнения
В Visual Studio нажмите клавишу F5, чтобы запустить отладчик. Первое, что начинается, — это приложение средства запуска PSF, которое, в свою очередь, запускает целевое классическое приложение. Чтобы выполнить отладку целевого классического приложения, необходимо вручную подключиться к процессу классического приложения, выбрав "Отладка —> присоединение к процессу" и выбрав процесс приложения. Чтобы разрешить отладку приложения .NET с собственной библиотекой DLL исправления среды выполнения, выберите управляемые и машинные типы кода (отладка в смешанном режиме).
После настройки можно задать точки останова рядом со строками кода в коде классического приложения и в проекте исправления среды выполнения. Если у вас нет исходного кода для приложения, вы сможете задать точки останова только рядом со строками кода в проекте исправления среды выполнения.
Так как отладка F5 запускает приложение путем развертывания свободных файлов из пути к папке макета пакета, а не установки из пакета .msix/.appx, папка макета обычно не имеет одинаковых ограничений безопасности, что и установленная папка пакета. В результате может быть невозможно воспроизвести ошибки отказа в доступе к пути пакета перед применением исправления среды выполнения.
Чтобы устранить эту проблему, используйте развертывание пакета MSIX/APPX, а не развертывание свободных файлов F5. Чтобы создать MSIX/APPX-файл пакета, используйте служебную программу MakeAppx из пакета Windows SDK, как описано выше. Кроме того, в Visual Studio щелкните правой кнопкой мыши узел проекта приложения и выберите "Магазин —> создать пакеты приложений".
Еще одна проблема с Visual Studio заключается в том, что у нее нет встроенной поддержки присоединения к дочерним процессам, запускаемым отладчиком. Это затрудняет отладку логики в пути запуска целевого приложения, которое должно быть подключено Visual Studio вручную после запуска.
Чтобы устранить эту проблему, используйте отладчик, поддерживающий присоединение дочерних процессов. Обратите внимание, что обычно невозможно подключить JIT-отладчик к целевому приложению. Это связано с тем, что большинство методов JIT включают запуск отладчика вместо целевого приложения с помощью раздела реестра ImageFileExecutionOptions. Это побеждает механизм обхода, используемый PSFLauncher.exe для внедрения FixupRuntime.dll в целевое приложение. WinDbg, включенная в средства отладки для Windows и полученная из Windows SDK, поддерживает присоединение дочернего процесса. Теперь она также поддерживает прямой запуск и отладку приложения 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 ...
Примечание
PLMDebug также можно использовать для присоединения отладчика к приложению при запуске, а также включается в средства отладки для Windows. Тем не менее, более сложно использовать, чем прямая поддержка, предоставляемая WinDbg.
Поддержка
Есть вопросы? Спросите нас о беседе платформы поддержки пакетов на сайте технического сообщества MSIX.