使用套件支援架構開始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. 修改套件以指向封裝支援架構 (.PSF) 啟動器可執行檔。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. 針對其中許多事件,[結果] 資料行中會出現「成功」這個字。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. PSFSample有兩個問題。The PSFSample has two issues. 您可以在清單中看到出現在下列影像中的問題。You can see those issues in the list that appears in the following image.

ProcMon Config.txt

在此影像中出現的第一個問題中,應用程式無法讀取位於 "C:\Windows\SysWOW64" 路徑中的 "Config.txt" 檔案。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 記錄檔

在此問題中,應用程式無法將 .log 檔寫入其封裝路徑。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

.PSF 包含您現在可以使用的執行時間修正,例如檔案重新導向修復。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 的安裝路徑為基礎,您可以在 Windows 10 電腦上找到 PC 上的 makeappx.exe 工具: x86: C:\Program 檔案 (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 命令列工具或 Visual Studio 來取得 .PSF Nuget 套件。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/downloadsInstall 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. 您需要的所有檔案都會在 [/bin] 資料夾底下。All the files you need will be under the /bin folder.

使用 Visual Studio 取得封裝Get 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. 搜尋 PackageSupportFramework.psf ,以在 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位 .PSF 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 為 .psf 啟動器可執行檔的名稱。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. 使用您從「進程監視器」取得的知識,您也可以設定工作目錄,也可以使用檔案重新導向修復來將讀取/寫入重新導向至封裝相關的 "PSFSampleApp" 目錄下的 .log 檔案。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 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 要載入之修復 msix/.appx 的封裝相對路徑。Package-relative path to the fixup, .msix/.appx 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.

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.

封裝和測試應用程式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 包含在 .PSF 中,並提供應用程式行為的詳細診斷視圖,類似于進程監視器。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. 在此範例中,我們不會附加偵錯工具,而會改為使用 SysInternals 的 DebugView 程式來查看其輸出。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.

找不到 TraceShim 檔案

拒絕 TraceShim 存取

偵錯工具、擴充或建立執行時間修正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
  • 新增啟動 .PSF 啟動器可執行檔的專案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
DesktopApplicationPackageDesktopApplicationPackage 此專案是以 Windows 應用程式封裝專案 為基礎,而且會輸出 MSIX 封裝。This project is based on the Windows Application Packaging project and it outputs the MSIX package.
RuntimefixRuntimefix 這是 c + + 動態連結的程式庫專案,其中包含一或多個做為執行時間修正的取代函數。This is a C++ Dynamic-Linked Library project that contains one or more replacement functions that serve as the runtime fix.
PSFLauncherPSFLauncher 這是 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.
WinFormsDesktopApplicationWinFormsDesktopApplication 此專案包含桌面應用程式的原始程式碼。This project contains the source code of a desktop application.

若要查看包含所有這些專案類型的完整範例,請參閱 PSFSampleTo 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

將 c + + **動態連結程式庫 (DLL) ** 專案加入至方案。Add a C++ Dynamic-Link Library (DLL) project to the solution.

執行時間修正程式庫

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

在 [屬性] 頁面中,尋找 [ c + + 語言標準 ] 欄位,然後在該欄位旁的下拉式清單中,選取 [ **ISO c + + 17 標準 (/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.

搜尋 .psf* 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.

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

將 c + + 空白專案 專案加入至方案。Add a C++ Empty Project project to the solution.

空專案

使用上一節所述的相同指導方針,將 .Psf 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.

.PSF 啟動器參考

將專案參考新增至方案中的執行時間修正專案。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 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.

新增專案參考

選擇 .PSF 啟動器專案和桌面應用程式專案,然後選擇 [ 確定] 按鈕。Choose the PSF Launcher project and your desktop application project, and then choose the OK button.

傳統型專案

注意

如果您的應用程式沒有原始程式碼,只要選擇 .PSF 啟動器專案即可。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.

在 [ 應用程式 ] 節點中,以滑鼠右鍵按一下 .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).

設定好之後,您可以在桌面應用程式程式碼和執行時間修正專案的程式程式碼旁設定中斷點。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 套件進行安裝,所以 layout 資料夾通常與安裝的封裝資料夾沒有相同的安全性限制。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 封裝檔案,請使用 Windows SDK 中的 MakeAppx 公用程式,如上面所述。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 技術都牽涉到透過 ImageFileExecutionOptions 登錄機碼來啟動偵錯工具,以取代目標應用程式。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 插入目標應用程式的 detouring 機制。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.

若要將目標應用程式啟動以子進程的形式啟動,請開始 WinDbgTo 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 ...

注意

PLMDebug 也可用來在啟動時,將偵錯工具附加至應用程式,也會包含在 適用于 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.