在 Visual Studio 中应用包支持框架

项目
10/30/2023

包支持框架 (PSF) 是一个开放源代码项目，可用于向现有桌面应用程序应用修复。 PSF 使应用程序能够以打包格式运行，而无需修改代码。包支持框架可帮助应用程序遵循新式运行时环境的最佳做法。

在以下部分中，我们将探讨如何创建新的 Visual Studio 项目，包括解决方案的包支持框架，以及创建运行时修复。

步骤 1：在 Visual Studio 中创建包解决方案

在 Visual Studio 中，创建新的“Visual Studio 解决方案, 空白解决方案”。将任何应用程序项目包含在新创建的“空白解决方案”中。

步骤 2：添加包项目

如果还没有“Windows 应用程序打包项目”，请创建一个项目并将其添加到解决方案。创建新的“Visual C#”->“Windows 通用”->“Windows 应用程序打包项目”，并将其添加到新创建的解决方案。

有关 Windows 应用程序打包项目的详细信息，请参阅使用 Visual Studio 打包应用程序。

在“解决方案资源管理器”中，右键单击打包项目，选择“编辑项目文件”，然后将其添加到项目文件的底部：

...
  <Target Name="PSFRemoveSourceProject" AfterTargets="ExpandProjectReferences" BeforeTargets="_ConvertItems">
    <ItemGroup>
      <FilteredNonWapProjProjectOutput Include="@(_FilteredNonWapProjProjectOutput)">
      <SourceProject Condition="'%(_FilteredNonWapProjProjectOutput.SourceProject)'=='_Runtime fix project name_'" />
      </FilteredNonWapProjProjectOutput>
      <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
      <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
    </ItemGroup>
  </Target>
</Project>

步骤 3：为运行时修复程序添加项目

添加新的“Visual C++”->“Windows 桌面”->“动态链接库 (DLL)”项目到解决方案。

下一步，右键单击项目，然后选择“属性”。

在属性页中，找到“配置属性”->“C/C++”->“语言”->“C++ 语言标准”字段。然后，从下拉菜单中选择 ISO C++17 标准 (/std:c++17)。

右键单击该项目，然后在上下文菜单中，选择“管理 Nuget 包”选项。确保“包源”选项设置为“全部”或 "nuget.org"。

单击该字段旁边的设置图标。

搜索 Nuget 包寻找 PSF，然后为此项目安装 Microsoft.PackageSupportFramework。

nuget package

步骤 4：添加启动 PSF 启动器可执行文件的项目

向解决方案添加新的“Visual C++”->“常规”->“空项目”。

执行以下步骤：

右键单击该项目，然后在上下文菜单中，选择“管理 Nuget 包”选项。确保“包源”选项设置为“全部”或 "nuget.org"。
单击该字段旁边的设置图标。
搜索 Nuget 包寻找 PSF，然后为此项目安装 Microsoft.PackageSupportFramework。

打开项目的属性页，然后在“常规”设置页中，根据应用程序的体系结构将“目标名称”属性设置为 PSFLauncher32 或 PSFLauncher64。

在解决方案中将项目引用添加到运行时修复程序项目。

右键单击引用，然后在“属性”窗口中应用这些值。

属性	Value
复制本地	True
复制本地附属程序集	True
引用程序集输出	True
链接库依赖项	False
链接库依赖项输入	False

步骤 5：配置打包项目

要配置打包项目，执行以下步骤：

在打包项目中，右键单击“应用程序”文件夹，然后从下拉菜单中选择“添加引用”。
选择 PSF 启动器项目和你的桌面应用程序项目，然后选择“确定”按钮。
同时选择“PSF 启动器”和“桌面应用程序”项目，然后单击“确定”按钮。如果应用程序源代码不可用，则仅选择 PSF 启动器项目。
在“应用程序”节点中，右键单击 PSF 启动器应用程序，然后选择“设置为入口点”。

将一个名为 config.json 的文件添加到打包项目，然后将以下 json 文本复制并粘贴到文件中。将“包操作”属性设置为“内容”。

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

为每个键提供一个值。使用此表作为指南。

数组	key	值
applications	id	使用包清单中 `Application` 元素的 `Id` 属性的值。
applications	可执行文件	要启动的可执行文件的包相对路径。在大多数情况下，可以在修改包清单文件之前从中获取此值。它是 `Application` 元素的 `Executable` 属性值。
applications	workingDirectory	（可选）要用作启动的应用程序之工作目录的包相对路径。如果未设置此值，操作系统将使用 `System32` 目录作为应用程序的工作目录。
进程	可执行文件	在大多数情况下，这是上面配置的 `executable` 的名称，只是删除了路径和文件扩展名。
修复	dll	要加载的修复 DLL 的包相对路径。
修复	config	（可选）控制修复 DLL 的行为方式。此值的确切格式因修复而异，因为每个修复都可以根据自己的需要解释此 "blob"。

完成后，config.json 文件将如下所示。

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

注意

applications、processes 和 fixups 键是数组。这意味着你可以使用 config.json 文件指定多个应用程序、进程和修复 DLL。

调试运行时修复程序

在 Visual Studio 中按 F5 启动调试器。首先启动的是 PSF 启动器应用程序，然后启动目标桌面应用程序。要调试目标桌面应用程序，必须通过选择“调试”->“附加到进程”，然后选择应用程序进程来手动附加到桌面应用程序进程。要允许使用本机运行时修复程序 DLL 调试 .NET 应用程序，请选择托管和本机代码类型（混合模式调试）。

你可以在桌面应用程序代码和运行时修复项目中的代码行旁边设置断点。如果没有应用程序的源代码，则只能在运行时修复程序项目中的代码行旁边设置断点。