Начало работы с платформой поддержки пакетовGet Started with Package Support Framework

Платформа поддержки пакетов — это набор с открытым исходным кодом, который помогает применять исправления к существующему классическому приложению (без изменения кода), чтобы его можно было запускать в контейнере MSIX.The Package Support Framework is an open source kit that helps you apply fixes to your existing desktop application (without modifying the code) so that it can run in an MSIX container. Платформа поддержки пакетов помогает настроить приложения в соответствии с требованиями современных сред выполнения.The Package Support Framework helps your application follow the best practices of the modern runtime environment.

Эта статья содержит подробные сведения о каждом компоненте платформы поддержки пакетов и пошаговое руководство по его использованию.This article provides an indepth look at each component of Package Support Framework and step by step guide to using it.

Узнайте, что входит в состав платформы поддержки пакетаUnderstand what is inside a Package Support Framework

Платформа поддержки пакетов содержит исполняемый файл, библиотеку DLL диспетчера среды выполнения и набор исправлений для среды выполнения.The Package Support Framework contains an executable, a runtime manager DLL, and a set of runtime fixes.

Платформа поддержки пакетов

Ниже приведен процесс.Here is the process:

  1. Создайте файл конфигурации, в котором будут указаны исправления, которые необходимо применить к приложению.Create a configuration file that specifies the fixes that you want to apply to your application.
  2. Измените пакет, чтобы он указывал на исполняемый файл средства запуска для платформы поддержки пакетов (ПСФ).Modify your package to point to the Package Support Framework (PSF) launcher executable file.

Когда пользователи запускают приложение, запускается средство запуска платформы поддержки пакетов. это первый исполняемый файл.When users starts your application, the Package Support Framework launcher is the first executable that runs. Он считывает файл конфигурации и внедряет исправления среды выполнения и библиотеку DLL диспетчера среды выполнения в процесс приложения.It reads your configuration file and injects the runtime fixes and the runtime manager DLL into the application process. Диспетчер среды выполнения применяет исправление, когда это требуется для выполнения приложения в контейнере MSIX.The runtime manager applies the fix when it's needed by the application to run inside of an MSIX container.

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

Шаг 1. выявление проблем совместимости упакованных приложенийStep 1: Identify packaged application compatibility issues

Сначала создайте пакет для своего приложения.First, create a package for your application. Затем установите его, запустите его и следите за его поведением.Then, install it, run it, and observe its behavior. Могут появиться сообщения об ошибке, которые помогут выявить проблемы с совместимостью.You might receive error messages that can help you identify a compatibility issue. Вы также можете использовать Монитор процесса для выявления проблем.You can also use Process Monitor to identify issues. Распространенные проблемы связаны с допущениями приложений о правах доступа к рабочему каталогу и пути программы.Common issues relate to application assumptions regarding the working directory and program path permissions.

Использование монитора процессов для обнаружения проблемыUsing Process Monitor to identify an issue

Монитор процессов — это мощная служебная программа для наблюдения за файлами и операциями реестра приложения, а также их результатами.Process Monitor is a powerful utility for observing an app's file and registry operations, and their results. Это может помочь в понимании проблем совместимости приложений.This can help you to understand application compatibility issues. После открытия монитора процессов добавьте фильтр (фильтр > фильтр...), чтобы включить только события из исполняемого файла приложения.After opening Process Monitor, add a filter (Filter > Filter…) to include only events from the application executable.

Фильтр приложений ProcMon

Появится список событий.A list of events will appear. Для многих из этих событий слово Success будет отображаться в столбце result .For many of these events, the word SUCCESS will appear in the Result column.

События ProcMon

При необходимости можно отфильтровать события, чтобы отображались только ошибки.Optionally, you can filter events to only show only failures.

ProcMon исключить успешное выполнение

Если вы считаете, что произошла ошибка доступа к файловой системе, выполните поиск событий со сбоем, которые находятся в папке System32/SysWOW64 или в пути к файлу пакета.If you suspect a filesystem access failure, search for failed events that are under either the System32/SysWOW64 or the package file path. Фильтры также могут помочь здесь.Filters can also help here, too. Начало в нижней части этого списка и прокрутка вверх.Start at the bottom of this list and scroll upwards. Ошибки, которые появляются в нижней части этого списка, были недавно выполнены.Failures that appear at the bottom of this list have occurred most recently. Обратите особое внимание на ошибки, содержащие такие строки, как "отказано в доступе" и "путь/имя не найдено", и пропускайте те вещи, которые не выглядят как подозрительные.Pay most attention to errors that contain strings such as "access denied," and "path/name not found", and ignore things that don't look suspicious. У псфсампле есть две проблемы.The PSFSample has two issues. Эти проблемы можно увидеть в списке, который отображается на следующем рисунке.You can see those issues in the list that appears in the following image.

ProcMon Config.txt

В первой выпуске, которая появляется на этом изображении, приложению не удается прочитать файл "Config.txt", расположенный в пути "C:\Windows\SysWOW64".In the first issue that appears in this image, the application is failing to read from the "Config.txt" file that is located in the "C:\Windows\SysWOW64" path. Маловероятно, что приложение пытается напрямую ссылаться на этот путь.It's unlikely that the application is trying to reference that path directly. Скорее всего, он пытается выполнить чтение из этого файла с помощью относительного пути, а по умолчанию system32/SysWOW64 — рабочий каталог приложения.Most likely, it's trying to read from that file by using a relative path, and by default, "System32/SysWOW64" is the application's working directory. Это предполагает, что приложение ожидает, что его текущий рабочий каталог устанавливается в любое место в пакете.This suggests that the application is expecting its current working directory to be set to somewhere in the package. Глядя на приложение appx, можно увидеть, что файл существует в том же каталоге, что и исполняемый объект.Looking inside of the appx, we can see that the file exists in the same directory as the executable.

Config.txt приложений

Вторая ошибка отображается на следующем рисунке.The second issue appears in the following image.

Файл журнала ProcMon

В этой ситуации приложению не удается записать файл журнала в путь пакета.In this issue, the application is failing to write a .log file to its package path. Это предложит, что может помочь адресная привязка перенаправления файлов.This would suggest that a file redirection fixup might help.

Шаг 2. Поиск исправления среды выполненияStep 2: Find a runtime fix

ПСФ содержит исправления среды выполнения, которые можно использовать прямо сейчас, например адресную привязку перенаправления файлов.The PSF contains runtime fixes that you can use right now, such as the file redirection fixup.

Адресная привязка перенаправления файловFile Redirection Fixup

С помощью адресной привязки перенаправления файлов можно перенаправить попытки записи или чтения данных в каталоге, который недоступен из приложения, работающего в контейнере MSIX.You can use the File Redirection Fixup to redirect attempts to write or read data in a directory that isn't accessible from an application that runs in an MSIX container.

Например, если приложение записывает в файл журнала, который находится в том же каталоге, что и исполняемые приложения, можно использовать адресную привязку перенаправления файлов , чтобы создать этот файл журнала в другом расположении, например в хранилище данных локального приложения.For example, if your application writes to a log file that is in the same directory as your applications executable, then you can use the File Redirection Fixup to create that log file in another location, such as the local app data store.

Исправления среды выполнения из сообществаRuntime fixes from the community

Обязательно ознакомьтесь с вкладами сообщества на нашу страницу GitHub .Make sure to review the community contributions to our GitHub page. Возможно, другие разработчики разрешили проблему, похожую на вашу, и предоставила исправление среды выполнения.It's possible that other developers have resolved an issue similar to yours and have shared a runtime fix.

Шаг 3. Применение исправления среды выполненияStep 3: Apply a runtime fix

Можно применить существующее исправление среды выполнения с помощью нескольких простых средств из Windows SDK и выполнить следующие действия.You can apply an existing runtime fix with a few simple tools from the Windows SDK, and by following these steps.

  • Создание папки макета пакетаCreate a package layout folder
  • Получение файлов платформы поддержки пакетовGet the Package Support Framework files
  • Добавьте их в пакетAdd them to your package
  • Изменение манифеста пакетаModify the package manifest
  • Создание файла конфигурацииCreate a configuration file

Давайте проверим каждую задачу.Let's go through each task.

Создание папки макета пакетаCreate the package layout folder

Если у вас уже есть файл. msix (или. appx), его содержимое можно распаковать в папку макета, которая будет служить промежуточной областью для пакета.If you have a .msix (or .appx) file already, you can unpack its contents into a layout folder that will serve as the staging area for your package. Это можно сделать из командной строки с помощью средства программе 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.exeYou can do this from a command prompt using MakeAppx tool, based on your installation path of the SDK, this is where you will find the makeappx.exe tool on your Windows 10 PC: 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

Это позволит получить примерно следующий вид.This will give you something that looks like the following.

Макет пакета

Если у вас нет файла. msix (или. appx), то можно создать папку пакета и файлы с нуля.If you don't have a .msix (or .appx) file to start with, you can create the package folder and files from scratch.

Получение файлов платформы поддержки пакетовGet the Package Support Framework files

Пакет NuGet для ПСФ можно получить с помощью автономного средства командной строки NuGet или с помощью Visual Studio.You can get the PSF Nuget package by using the standalone Nuget command line tool or via Visual Studio.

Получение пакета с помощью программы командной строкиGet the package by using the command line tool

Установите программу командной строки NuGet из этого расположения: https://www.nuget.org/downloads .Install the Nuget command line tool from this location: https://www.nuget.org/downloads. Затем в командной строке NuGet выполните следующую команду:Then, from the Nuget command line, run this command:

nuget install Microsoft.PackageSupportFramework

Кроме того, можно переименовать расширение пакета в ZIP-файл и распаковать его.Alternatively, you can rename the package extension to .zip and unzip it. Все необходимые файлы будут находиться в папке "переносить".All the files you need will be under the /bin folder.

Получение пакета с помощью Visual StudioGet the package by using Visual Studio

В Visual Studio щелкните правой кнопкой мыши узел решения или проекта и выберите одну из команд Управление пакетами NuGet.In Visual Studio, right-click your solution or project node and pick one of the Manage Nuget Packages commands. Найдите Microsoft. паккажесуппортфрамеворк или ПСФ , чтобы найти пакет на NuGet.org. Затем установите его.Search for Microsoft.PackageSupportFramework or PSF to find the package on Nuget.org. Then, install it.

Добавление файлов платформы поддержки пакетов в пакетAdd the Package Support Framework files to your package

Добавьте необходимые 32-разрядные и 64-битные ПСФ DLL и исполняемые файлы в каталог пакета.Add the required 32-bit and 64-bit PSF DLLs and executable files to the package directory. Руководствуйтесь следующей таблицей.Use the following table as a guide. Также необходимо включить все необходимые исправления среды выполнения.You'll also want to include any runtime fixes that you need. В нашем примере нам требуется исправление среды выполнения для перенаправления файлов.In our example, we need the file redirection runtime fix.

Исполняемый файл приложения — x64Application executable is x64 Исполняемый файл приложения — x86Application executable is x86
PSFLauncher64.exePSFLauncher64.exe PSFLauncher32.exePSFLauncher32.exe
PSFRuntime64.dllPSFRuntime64.dll PSFRuntime32.dllPSFRuntime32.dll
PSFRunDll64.exePSFRunDll64.exe PSFRunDll32.exePSFRunDll32.exe

Теперь содержимое пакета должно выглядеть примерно так:Your package content should now look something like this.

Двоичные файлы пакета

Изменение манифеста пакетаModify the package manifest

Откройте манифест пакета в текстовом редакторе, а затем присвойте Executable атрибуту Application элемента имя исполняемого файла средства запуска ПСФ.Open your package manifest in a text editor, and then set the Executable attribute of the Application element to the name of the PSF Launcher executable file. Если вы знакомы с архитектурой целевого приложения, выберите соответствующую версию, PSFLauncher32.exe или PSFLauncher64.exe.If you know the architecture of your target application, select the appropriate version, PSFLauncher32.exe or PSFLauncher64.exe. В противном случае PSFLauncher32.exe будет работать во всех случаях.If not, PSFLauncher32.exe will work in all cases. Рассмотрим пример.Here's an example.

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

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

Создайте имя файла config.json и сохраните его в корневую папку пакета.Create a file name config.json, and save that file to the root folder of your package. Измените объявленный идентификатор приложения config.jsв файле, чтобы он указывал на только что замененный исполняемый файл.Modify the declared app ID of the config.json file to point to the executable that you just replaced. С помощью набора знаний, полученного с помощью монитора процессов, можно также задать рабочий каталог, а также использовать адресную привязку перенаправления файлов для перенаправления операций чтения и записи в файлы журнала в папке с относительным пакетом "Псфсамплеапп".Using the knowledge that you gained from using Process Monitor, you can also set the working directory as well as use the file redirection fixup to redirect reads/writes to .log files under the package-relative "PSFSampleApp" directory.

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

Ниже приведено руководство по config.jsсхеме.Following is a guide for the config.json schema:

ArrayArray ключkey ЗначениеValue
веб-масштабированием;applications идентификаторid Используйте значение Id атрибута Application элемента в манифесте пакета.Use the value of the Id attribute of the Application element in the package manifest.
веб-масштабированием;applications исполняемый файлexecutable Относительный путь пакета к исполняемому файлу, который необходимо запустить.The package-relative path to the executable that you want to start. В большинстве случаев это значение можно получить из файла манифеста пакета, прежде чем изменять его.In most cases, you can get this value from your package manifest file before you modify it. Это значение Executable атрибута Application элемента.It's the value of the Executable attribute of the Application element.
веб-масштабированием;applications workingDirectoryworkingDirectory Используемых Путь относительно пакета, используемый в качестве рабочего каталога запускаемого приложения.(Optional) A package-relative path to use as the working directory of the application that starts. Если это значение не задано, операционная система использует каталог в System32 качестве рабочего каталога приложения.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
процессыprocesses исполняемый файлexecutable В большинстве случаев это будет имя, указанное executable выше, с удаленным путем и расширением файла.In most cases, this will be the name of the executable configured above with the path and file extension removed.
исправленийfixups Файл DLL.dll Относительный путь пакета к адресной привязке,. msix/. appx для загрузки.Package-relative path to the fixup, .msix/.appx to load.
исправленийfixups configconfig Используемых Определяет, как ведет себя библиотека DLL адресной привязки.(Optional) Controls how the fixup dll behaves. Точный формат этого значения зависит от способа исправления, так как каждая адресная привязка может интерпретировать этот «большой двоичный объект».The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

applicationsКлючи, processes и fixups являются массивами.The applications, processes, and fixups keys are arrays. Это означает, что вы можете использовать config.jsв файле, чтобы указать более одного DLL приложения, процесса и адресной привязки.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Упаковка и тестирование приложенияPackage and test the app

Затем создайте пакет.Next, create a package.

makeappx pack /d PackageContents /p PSFSamplePackageFixup.msix

Затем подпишите его.Then, sign it.

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

Дополнительные сведения см. в статьях Создание сертификата для подписи пакета и Подписывание пакета с помощью средства SignTool .For more information, see how to create a package signing certificate and how to sign a package using signtool

С помощью PowerShell установите пакет.Using PowerShell, install the package.

Примечание

Не забудьте сначала удалить пакет.Remember to uninstall the package first.

powershell Add-AppPackage .\PSFSamplePackageFixup.msix

Запустите приложение и обратите внимание на поведение с применением исправления среды выполнения.Run the application and observe the behavior with runtime fix applied. При необходимости повторите шаги диагностики и упаковки.Repeat the diagnostic and packaging steps as necessary.

Проверьте, запущена ли платформа поддержки пакетов.Check whether the Package Support Framework is running

Вы можете проверить, выполняется ли исправление среды выполнения.You can check whether your runtime fix is running. Для этого откройте Диспетчер задач и щелкните Дополнительные сведения.A way to do this is to open Task Manager and click More details. Найдите приложение, к которому применена платформа поддержки пакетов, и разверните сведения о приложении, чтобы веив более подробную информацию.Find the app that the package support framework was applied to and expand the app detail to veiw more details. Вы сможете увидеть, что платформа поддержки пакетов запущена.You should be able to view that the Package Support Framework is running.

Использование исправления трассировкиUse the Trace Fixup

Альтернативный способ диагностики проблем совместимости упакованных приложений заключается в использовании исправления трассировки.An alternative technique to diagnosing packaged application compatibility issues is to use the Trace Fixup. Эта библиотека DLL входит в состав ПСФ и предоставляет подробное диагностическое представление о поведении приложения, аналогичное монитору процессов.This DLL is included with the PSF and provides a detailed diagnostic view of the app's behavior, similar to Process Monitor. Он специально разработан для выявления проблем совместимости приложений.It is specially designed to reveal application compatibility issues. Чтобы использовать исправление трассировки, добавьте в пакет библиотеку DLL, добавьте следующий фрагмент в config.js, а затем упакуйте и установите приложение.To use the Trace Fixup, add the DLL to the package, add the following fragment to your config.json, and then package and install your application.

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

По умолчанию исправление трассировки отфильтровывает сбои, которые могут считаться ожидаемыми.By default, the Trace Fixup filters out failures that might be considered "expected". Например, приложения могут попытаться безусловно удалить файл без проверки его существования, игнорируя результат.For example, applications might try to unconditionally delete a file without checking to see if it already exists, ignoring the result. Это имеет следствие, что некоторые непредвиденные сбои могут быть отфильтрованы, поэтому в приведенном выше примере мы будем выбирать получение всех сбоев из функций файловой системы.This has the unfortunate consequence that some unexpected failures might get filtered out, so in the above example, we opt to receive all failures from filesystem functions. Это делается потому, что перед попыткой чтения из файла Config.txt происходит сбой с сообщением «файл не найден».We do this because we know from before that the attempt to read from the Config.txt file fails with the message "file not found". Это сбой, который часто наблюдается и обычно не предполагается непредвиденным.This is a failure that is frequently observed and not generally assumed to be unexpected. На практике лучше всего начать фильтрацию только до непредвиденных сбоев, а затем вернуться ко всем сбоям, если есть проблема, которую по-прежнему невозможно определить.In practice it's likely best to start out filtering only to unexpected failures, and then falling back to all failures if there's an issue that still can't be identified.

По умолчанию выходные данные исправления трассировки отправляются в подключенный отладчик.By default, the output from the Trace Fixup gets sent to the attached debugger. В этом примере мы не будем подключать отладчик и используем программу DebugView из Sysinternals для просмотра ее выходных данных.For this example, we aren't going to attach a debugger, and will instead use the DebugView program from SysInternals to view its output. После запуска приложения можно увидеть те же сбои, что и раньше, что указывает нам на те же исправления среды выполнения.After running the app, we can see the same failures as before, which would point us towards the same runtime fixes.

Файл Трацешим не найден

Отказано в доступе к Трацешим

Отладка, расширение или создание исправления среды выполненияDebug, extend, or create a runtime fix

Visual Studio можно использовать для отладки исправления среды выполнения, расширения среды выполнения или создания одной из них с нуля.You can use Visual Studio to debug a runtime fix, extend a runtime fix, or create one from scratch. Для успешного выполнения этих действий необходимо выполнить следующие действия.You'll need to do these things to be successful.

  • Добавление проекта упаковкиAdd a packaging project
  • Добавление проекта для исправления среды выполненияAdd project for the runtime fix
  • Добавление проекта, запускающего исполняемый файл запуска ПСФAdd a project that starts the PSF Launcher executable
  • Настройка проекта упаковкиConfigure the packaging project

По завершении решение будет выглядеть примерно так.When you're done, your solution will look something like this.

Завершенное решение

Рассмотрим каждый проект в этом примере.Let's look at each project in this example.

ProjectProject ЦельPurpose
десктопаппликатионпаккажеDesktopApplicationPackage Этот проект основан на проекте упаковки приложений Windows и выводит пакет MSIX.This project is based on the Windows Application Packaging project and it outputs the MSIX package.
рунтимефиксRuntimefix Это проект библиотеки C++ с динамической присоединением, который содержит одну или несколько функций замены, которые служат исправлением среды выполнения.This is a C++ Dynamic-Linked Library project that contains one or more replacement functions that serve as the runtime fix.
псфлаунчерPSFLauncher Это пустой проект на языке C++.This is C++ Empty Project. Этот проект является местом для получения распространяемых файлов среды выполнения платформы поддержки пакетов.This project is a place to collect the runtime distributable files of the Package Support Framework. Он выводит исполняемый файл.It outputs an executable file. Этот исполняемый файл является первым, который запускается при запуске решения.That executable is the first thing that runs when you start the solution.
винформсдесктопаппликатионWinFormsDesktopApplication Этот проект содержит исходный код для классического приложения.This project contains the source code of a desktop application.

Полный пример, содержащий все типы проектов, см. в разделе псфсампле.To look at a complete sample that contains all of these types of projects, see PSFSample.

Давайте рассмотрим шаги по созданию и настройке каждого из этих проектов в решении.Let's walk through the steps to create and configure each of these projects in your solution.

Создание решения пакетаCreate a package solution

Если у вас еще нет решения для классического приложения, создайте новое пустое решение в Visual Studio.If you don't already have a solution for your desktop application, create a new Blank Solution in Visual Studio.

Пустое решение

Вам также может потребоваться добавить любые проекты приложений, которые у вас есть.You may also want to add any application projects you have.

Добавление проекта упаковкиAdd a packaging project

Если у вас еще нет проекта упаковки приложений Windows, создайте его и добавьте в решение.If you don't already have a Windows Application Packaging Project, create one and add it to your solution.

Шаблон проекта пакета

Дополнительные сведения о проекте упаковки приложений Windows см. в статье Упаковка приложения с помощью Visual Studio.For more information on Windows Application Packaging project, see Package your application by using Visual Studio.

В Обозреватель решенийщелкните проект упаковки правой кнопкой мыши, выберите изменить, а затем добавьте в конец файла проекта:In Solution Explorer, right-click the packaging project, select Edit, and then add this to the bottom of the project file:

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

Добавление проекта для исправления среды выполненияAdd project for the runtime fix

Добавьте в решение проект библиотеки динамической компоновки (DLL) C++.Add a C++ Dynamic-Link Library (DLL) project to the solution.

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

Щелкните правой кнопкой мыши этот проект и выберите пункт Свойства.Right-click the that project, and then choose Properties.

На страницах свойств найдите поле стандарт языка C++ , а затем в раскрывающемся списке рядом с этим полем Выберите параметр ISO C++ 17 Standard (/std: c++ 17) .In the property pages, find the C++ Language Standard field, and then in the drop-down list next to that field, select the ISO C++17 Standard (/std:c++17) option.

Параметр ISO 17

Щелкните правой кнопкой мыши этот проект, а затем в контекстном меню выберите пункт Управление пакетами NuGet .Right-click that project, and then in the context menu, choose the Manage Nuget Packages option. Убедитесь, что для параметра источник пакета задано значение все или NuGet.org.Ensure that the Package source option is set to All or nuget.org.

Щелкните значок параметров рядом с этим полем.Click the settings icon next that field.

Найдите пакет NuGet *ПСФ**, а затем установите его для этого проекта.Search for the PSF* Nuget package, and then install it for this project.

пакет nuget

Если требуется выполнить отладку или расширение существующего исправления среды выполнения, добавьте файлы исправления среды выполнения, полученные с помощью инструкций, описанных в разделе Поиск исправления среды выполнения этого руководства.If you want to debug or extend an existing runtime fix, add the runtime fix files that you obtained by using the guidance described in the Find a runtime fix section of this guide.

Если вы собираетесь создать новое исправление, не добавляйте его в проект еще раз.If you intend to create a brand new fix, don't add anything to this project just yet. Мы поможем вам добавить нужные файлы в этот проект позже.We'll help you add the right files to this project later in this guide. Сейчас мы продолжим настройку решения.For now, we'll continue setting up your solution.

Добавление проекта, запускающего исполняемый файл запуска ПСФAdd a project that starts the PSF Launcher executable

Добавьте в решение пустой проект проекта C++.Add a C++ Empty Project project to the solution.

Пустой проект

Добавьте пакет NuGet ПСФ в этот проект с помощью тех же руководств, которые описаны в предыдущем разделе.Add the PSF Nuget package to this project by using the same guidance described in the previous section.

Откройте страницы свойств для проекта и на странице Общие параметры задайте для свойства имя целевого объекта значение PSFLauncher32 или в PSFLauncher64 зависимости от архитектуры приложения.Open the property pages for the project, and in the General settings page, set the Target Name property to PSFLauncher32 or PSFLauncher64 depending on the architecture of your application.

Справочник по средству запуска ПСФ

Добавьте ссылку проекта в проект исправления среды выполнения в решении.Add a project reference to the runtime fix project in your solution.

Справочник по исправлению среды выполнения

Щелкните ссылку правой кнопкой мыши, а затем в окне Свойства примените эти значения.Right-click the reference, and then in the Properties window, apply these values.

Property (Свойство)Property ЗначениеValue
Копировать локальноCopy local ВерноTrue
Копировать локальные вспомогательные сборкиCopy Local Satellite Assemblies ВерноTrue
Выходные данные ссылочной сборкиReference Assembly Output ВерноTrue
Компоновать зависимости библиотекLink Library Dependencies НетFalse
Связывание входных данных зависимостей библиотекиLink Library Dependency Inputs НетFalse

Настройка проекта упаковкиConfigure the packaging project

В проекте упаковки щелкните правой кнопкой мыши папку Приложения и выберите Добавить ссылку.In the packaging project, right-click the Applications folder, and then choose Add Reference.

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

Выберите проект средства запуска ПСФ и проект приложения рабочего стола, а затем нажмите кнопку ОК .Choose the PSF Launcher project and your desktop application project, and then choose the OK button.

Проект классического приложения

Примечание

Если у вас нет исходного кода приложения, просто выберите проект ПСФ Launcher.If you don't have the source code to your application, just choose the PSF Launcher project. Мы покажем, как ссылаться на исполняемый файл при создании файла конфигурации.We'll show you how to reference your executable when you create a configuration file.

В узле приложения щелкните правой кнопкой мыши приложение ПСФ Launcher и выберите пункт задать в качестве точки входа.In the Applications node, right-click the PSF Launcher application, and then choose Set as Entry Point.

Задать как точку входа

Добавьте файл с именем config.json в проект упаковки, а затем скопируйте и вставьте следующий текст JSON в файл.Add a file named config.json to your packaging project, then, copy and paste the following json text into the file. Задайте для свойства действие пакета значение содержимое.Set the Package Action property to Content.

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

Укажите значение для каждого ключа.Provide a value for each key. Используйте эту таблицу в качестве справочника.Use this table as a guide.

ArrayArray ключkey ЗначениеValue
веб-масштабированием;applications идентификаторid Используйте значение Id атрибута Application элемента в манифесте пакета.Use the value of the Id attribute of the Application element in the package manifest.
веб-масштабированием;applications исполняемый файлexecutable Относительный путь пакета к исполняемому файлу, который необходимо запустить.The package-relative path to the executable that you want to start. В большинстве случаев это значение можно получить из файла манифеста пакета, прежде чем изменять его.In most cases, you can get this value from your package manifest file before you modify it. Это значение Executable атрибута Application элемента.It's the value of the Executable attribute of the Application element.
веб-масштабированием;applications workingDirectoryworkingDirectory Используемых Путь относительно пакета, используемый в качестве рабочего каталога запускаемого приложения.(Optional) A package-relative path to use as the working directory of the application that starts. Если это значение не задано, операционная система использует каталог в System32 качестве рабочего каталога приложения.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
процессыprocesses исполняемый файлexecutable В большинстве случаев это будет имя, указанное executable выше, с удаленным путем и расширением файла.In most cases, this will be the name of the executable configured above with the path and file extension removed.
исправленийfixups Файл DLL.dll Относительный путь пакета к библиотеке DLL адресной привязки для загрузки.Package-relative path to the fixup DLL to load.
исправленийfixups configconfig Используемых Определяет, как ведет себя библиотека DLL адресной привязки.(Optional) Controls how the fixup DLL behaves. Точный формат этого значения зависит от способа исправления, так как каждая адресная привязка может интерпретировать этот «большой двоичный объект».The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

По завершении config.json файл будет выглядеть примерно так.When you're done, your config.json file will look something like this.

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

Примечание

applicationsКлючи, processes и fixups являются массивами.The applications, processes, and fixups keys are arrays. Это означает, что вы можете использовать config.jsв файле, чтобы указать более одного DLL приложения, процесса и адресной привязки.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

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

В Visual Studio нажмите клавишу F5, чтобы запустить отладчик.In Visual Studio, press F5 to start the debugger. Первое, что начинается, — это приложение ПСФ Launcher, которое, в свою очередь, запускает целевое классическое приложение.The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop application. Чтобы выполнить отладку целевого настольного приложения, необходимо вручную присоединиться к процессу настольного приложения, выбрав отладка >присоединить к процессу, а затем выбрав процесс приложения.To debug the target desktop application, you'll have to manually attach to the desktop application process by choosing Debug->Attach to Process, and then selecting the application process. Чтобы разрешить отладку приложения .NET с помощью встроенной библиотеки DLL с исправлением среды выполнения, выберите управляемые и машинные типы кода (Отладка в смешанном режиме).To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging).

После настройки можно задать точки останова рядом с строками кода в коде приложения для настольных систем и в проекте исправления среды выполнения.Once you've set this up, you can set break points next to lines of code in the desktop application code and the runtime fix project. Если у вас нет исходного кода для приложения, вы сможете устанавливать точки останова только рядом с строками кода в проекте исправления среды выполнения.If you don't have the source code to your application, you'll be able to set break points only next to lines of code in your runtime fix project.

Поскольку отладка F5 запускает приложение, развертывая свободные файлы из пути к папке макета пакета, а не устанавливая из пакета. msix/. appx, папка макета обычно не имеет тех же ограничений безопасности, что и папка установленного пакета.Because F5 debugging runs the application by deploying loose files from the package layout folder path, rather than installing from a .msix/.appx package, the layout folder typically does not have the same security restrictions as an installed package folder. В результате может быть невозможно воспроизвести ошибки отказа при доступе к пути пакета перед применением исправления среды выполнения.As a result, it may not be possible to reproduce package path access denial errors prior to applying a runtime fix.

Чтобы устранить эту ошибку, используйте развертывание пакета. msix/. appx вместо нажатия клавиши F5 для недостаточного развертывания файлов.To address this issue, use .msix / .appx package deployment rather than F5 loose file deployment. Чтобы создать файл пакета msix/. appx, используйте служебную программу программе makeappx из Windows SDK, как описано выше.To create a .msix / .appx package file, use the MakeAppx utility from the Windows SDK, as described above. Или в среде Visual Studio щелкните правой кнопкой мыши узел проекта приложения и выберите пункт магазин — > создать пакеты приложений.Or, from within Visual Studio, right-click your application project node and select Store -> Create App Packages.

Другой проблемой в Visual Studio является отсутствие встроенной поддержки присоединения к любым дочерним процессам, запущенным отладчиком.Another issue with Visual Studio is that it does not have built-in support for attaching to any child processes launched by the debugger. Это затрудняет отладку логики в пути запуска целевого приложения, который должен быть вручную присоединен Visual Studio после запуска.This makes it difficult to debug logic in the startup path of the target application, which must be manually attached by Visual Studio after launch.

Чтобы устранить эту ошибку, используйте отладчик, который поддерживает присоединение дочернего процесса.To address this issue, use a debugger that supports child process attach. Обратите внимание, что обычно невозможно присоединить JIT-отладчик к целевому приложению.Note that it is generally not possible to attach a just-in-time (JIT) debugger to the target application. Это связано с тем, что большинство методов JIT подразумевает запуск отладчика вместо целевого приложения с помощью раздела реестра Имажефиликсекутионоптионс.This is because most JIT techniques involve launching the debugger in place of the target app, via the ImageFileExecutionOptions registry key. Это нарушает механизм дедемонстрации, используемый PSFLauncher.exe для внедрения FixupRuntime.dll в целевое приложение.This defeats the detouring mechanism used by PSFLauncher.exe to inject FixupRuntime.dll into the target app. WinDbg, который входит в средства отладки для Windowsи получен из Windows SDK, поддерживает присоединение дочернего процесса.WinDbg, included in the Debugging Tools for Windows, and obtained from the Windows SDK, supports child process attach. Теперь он также поддерживает непосредственное Запуск и отладку приложения UWP.It also now supports directly launching and debugging a UWP app.

Для отладки запуска целевого приложения в качестве дочернего процесса запустите WinDbg .To debug target application startup as a child process, start WinDbg.

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

В WinDbg командной строке включите дочернюю отладку и установите соответствующие точки останова.At the WinDbg prompt, enable child debugging and set appropriate breakpoints.

.childdbg 1
g

(выполнение до запуска и переноса целевого приложения в отладчик)(execute until target application starts and breaks into the debugger)

sxe ld fixup.dll
g

(выполнить до загрузки библиотеки DLL адресной привязки)(execute until the fixup DLL is loaded)

bp ...

Примечание

Плмдебуг можно также использовать для подключения отладчика к приложению при запуске и также включен в средства отладки для Windows.PLMDebug can be also used to attach a debugger to an app upon launch, and is also included in the Debugging Tools for Windows. Однако использование более сложно, чем прямая поддержка, предоставляемая WinDbg.However, it is more complex to use than the direct support now provided by WinDbg.

ПоддержкаSupport

Есть вопросы?Have questions? Попросите нас обратиться в конференцию по платформе поддержки пакетов на сайте технического сообщества MSIX.Ask us on the Package Support Framework conversation space on the MSIX tech community site.