在 Visual Studio 中套用套件支援架構Apply Package Support Framework in Visual Studio

封裝支援架構 (.PSF) 是 開放原始碼專案 ,可讓您將修正程式套用至現有的桌面應用程式。The Package Support Framework (PSF) is an open source project that enables you to apply fixes to your existing desktop application. .PSF 可讓應用程式以 MSIX 封裝格式執行,而不需要修改程式碼。The PSF enables an application to run in an MSIX packaged format without modifying code. 套件支援架構有助於讓應用程式遵循最新執行階段環境的最佳做法。The Package Support Framework helps your application follow the best practices of the modern runtime environment.

在下列各節中,我們將探討如何建立新的 Visual Studio 專案、將封裝支援架構包含到方案,以及建立執行時間修正。In the following sections, we will explore how to create a new Visual Studio project, include Package Support Framework to the solution, and create runtime fixes.

步驟1:在 Visual Studio 中建立封裝方案Step 1: Create a package solution in Visual Studio

在 Visual Studio 中,建立新的 Visual Studio 解決方案、空白的方案In Visual Studio, create a new Visual Studio Solutions, Blank Solution . 將任何應用程式專案包含在新建立的 空白方案 中。Include any application projects to the newly created Blank Solution .

步驟2:新增封裝專案Step 2: Add a packaging project

如果您還沒有 Windows 應用程式封裝專案 ,請建立一個,並將其新增至您的方案。If you don't already have a Windows Application Packaging Project , create one and add it to your solution. 建立新的 Visual c #-> Windows 通用 > Windows 應用程式封裝專案 並將它新增至新建立的方案。Create a new Visual C# -> Windows Universal -> Windows Application Packaging Project and add it to your newly created 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 Project File , 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)'=='_Runtime fix project name_'" />
      </FilteredNonWapProjProjectOutput>
      <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
      <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
    </ItemGroup>
  </Target>
</Project>

步驟3:新增執行時間修正的專案Step 3: Add project for the runtime fix

在方案中加入新的 Visual C++ > Windows Desktop-> Dynamic-Link 程式庫 (DLL ) 專案。Add a new Visual C++ -> Windows Desktop -> Dynamic-Link Library (DLL) project to the solution.

接下來,以滑鼠右鍵按一下該專案,然後選擇 [ 屬性 ]。Next, right-click the that project, and then choose Properties .

在 [屬性] 頁面中,找出設定 屬性-> c/c + +-> 語言 > c + + 語言標準 欄位。In the property page, locate the Configuration Properties -> C/C++ -> Language -> C++ Language Standard field. 然後從下拉式功能表中選取 [ISO c + + 17 標準 (/std: c + + 17) 。Then select ISO C++17 Standard (/std:c++17) from the drop-down menu.

以滑鼠右鍵按一下專案,然後在內容功能表中,選擇 [ 管理 Nuget 封裝 ] 選項。Right-click on the 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.

搜尋適用于 .psf 的 Nuget 套件,然後安裝此專案的 PackageSupportFrameworkSearch the Nuget packages for PSF , then install the Microsoft.PackageSupportFramework for this project.

nuget 套件

步驟4:新增啟動 .PSF 啟動器可執行檔的專案Step 4: Add a project that starts the PSF Launcher executable

將新的 Visual C++ > 一般 > 空白專案 加入至方案。Add a new Visual C++ -> General -> Empty Project to the solution.

請執行下列步驟:Do the following steps:

  1. 以滑鼠右鍵按一下該專案,然後在內容功能表中,選擇 [ 管理 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 .
  2. 按一下該欄位旁的設定圖示。Click the settings icon next that field.
  3. 搜尋適用于 .PSF 的 Nuget 套件,然後安裝此專案的 PackageSupportFramework。Search the Nuget packages for PSF, then install the Microsoft.PackageSupportFramework for this project.

開啟專案的 屬性頁 ,然後在 [ 一般 設定] 頁面中,將 [ 目標名稱 ] 屬性設定為 PSFLauncher32 或, PSFLauncher64 視您應用程式的架構而定。Open the properties 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 Value
複製到本機Copy local TrueTrue
複製附屬組件到本機Copy Local Satellite Assemblies TrueTrue
參考組件輸出Reference Assembly Output TrueTrue
連結程式庫相依性Link Library Dependencies FalseFalse
程式庫相依性輸入Link Library Dependency Inputs FalseFalse

步驟5:設定封裝專案Step 5: Configure the packaging project

若要設定封裝專案,請執行下列步驟:To configure the packaging project do the following steps:

  1. 在封裝專案中,以滑鼠右鍵按一下 [ 應用程式 ] 資料夾,然後從下拉式功能表中選擇 [ 加入參考 ]。In the packaging project, right-click the Applications folder, and then choose Add Reference from the dropdown menu.
  2. 選擇 .PSF 啟動器專案和桌面應用程式專案,然後選擇 [ 確定] 按鈕。Choose the PSF Launcher project and your desktop application project, and then choose the OK button.
  3. 選取 .Psf 啟動器桌面應用程式 專案,然後按一下 [確定] 按鈕。Select both the PSF Launcher and the Desktop Application project, then click the Ok button. 如果無法使用應用程式原始程式碼,請只選取 .PSF 啟動器專案。If the application source code is not available, select only the PSF Launcher project.
  4. 在 [ 應用程式 ] 節點中,以滑鼠右鍵按一下 .psf 啟動器應用程式,然後選擇 [ 設定為進入點 ]。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 idid 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 ApplicationIt'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 dlldll 要載入之修復 DLL 的封裝相對路徑。Package-relative path to the fixup DLL to load.
修復fixups configconfig (選擇性) 控制修復 DLL 的運作方式。(Optional) Controls how the fixup DLL behaves. 此值的確切格式會因修復修復而異,因為每個修復可以視需要解讀此「blob」。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" } ]
    }
  ]
}

注意

applicationsprocesses 和索引 fixups 鍵是陣列。The applications, processes, and fixups keys are arrays. 這表示您可以使用 config.json file 來指定多個應用程式、進程和修復 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. 首先,第一件事是 .PSF 啟動器應用程式,它接著會啟動您的目標桌面應用程式。The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop application. 若要進行目標桌面應用程式的偵錯工具,您必須選擇 [ debug->附加至進程 ],然後選取應用程式進程,以手動方式附加至桌面應用程式進程。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. 若要允許使用原生執行時間修正 DLL 來進行 .NET 應用程式的偵錯工具,請選取 managed 和機器碼類型 (混合模式的偵錯工具) 。To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging).

您可以在桌面應用程式程式碼中的程式程式碼旁設定中斷點,並在執行時間修正專案中設定中斷點。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.