MSIX パッケージにパッケージのサポートのフレームワークを使用してランタイム修正プログラムを適用します。Apply runtime fixes to an MSIX package by using the Package Support Framework

パッケージのサポート、フレームワークは、修正プログラムを適用、既存の win32 アプリケーションに、ソース コードへのアクセス権がないときに、MSIX コンテナーで実行できるようにするのに役立つオープン ソース キット。The Package Support Framework is an open source kit that helps you apply fixes to your existing win32 application when you don't have access to the source 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.

詳細についてを参照してください。パッケージ サポート フレームワークします。To learn more, see Package Support Framework.

このガイドを利用するアプリケーションの互換性の問題を特定して、検索、適用、およびランタイムを拡張するには、それらに対処するを修正します。This guide will help you to identify application compatibility issues, and to find, apply, and extend runtime fixes that address them.

パッケージ化されたアプリケーションの互換性の問題を特定します。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.

Process Monitor を使用して、問題を識別するには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. Process Monitor を開いた後、フィルターの追加 (フィルター > フィルター...) アプリケーションの実行可能ファイルからのイベントのみを含めます。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. "パス/名前 not found"、「アクセスが拒否されると、」などの文字列が含まれているエラーをほとんど注意し、不審な外観がないことを無視します。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は 2 つの問題があります。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

2 つ目の問題は、次の図に表示されます。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.

ランタイム修正プログラムを検索します。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

使用することができます、ファイル リダイレクト 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.

などの場合は、アプリケーションの実行可能ファイルと同じディレクトリ内にあるログ ファイルに書き込むと、アプリケーション、しを使用できます、ファイル リダイレクト Fixupローカル アプリのデータ ストアなどの別の場所にそのログ ファイルを作成します。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.

ランタイム修正プログラムを適用します。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. SDK のインストール パスに基づく MakeAppx ツールを使用してコマンド プロンプトから実行することが、これは、Windows 10 PC で makeappx.exe ツールを表示します 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

PSF 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

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. 検索Microsoft.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.json ファイルの宣言されたアプリ ID を変更します。Modify the declared app ID of the config.json file to point to the executable that you just replaced. Process Monitor を使用してから、獲得した知識を使用して、することができますも作業ディレクトリの設定だけでなくファイル リダイレクト フィックス アップを使用してパッケージ相対"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.json スキーマのためのガイドを次に示します。Following is a guide for the config.json schema:

配列Array keykey ValueValue
applicationsapplications idid 値を使用して、Idの属性、Applicationパッケージ マニフェスト内の要素。Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications 実行可能ファイル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.
applicationsapplications 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 構成config (省略可能)フィックス アップ dl の動作を制御します。(Optional) Controls how the fixup dl 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. つまり、1 つ以上のアプリケーション、プロセス、および DLL のフィックス アップを指定する config.json ファイルを使用することができます。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.

トレースのフィックス アップを使用して、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.json に次のフラグメントを追加しパッケージ化をし使用するアプリケーションをインストールします。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. これは、上記の例では、ことを選択します filesystem 関数からすべてのエラーを受信するためのいくつかの予期しないエラーが取得除外された、残念な結果です。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.

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 これは、ランタイム修正プログラムとして機能する 1 つまたは複数の置換関数を含む C++ Dynamic-Linked ライブラリ プロジェクトです。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.

これらの種類のプロジェクトのすべてを含む完全なサンプルを見るを参照してください。 PSFSampleします。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 アプリケーション パッケージ プロジェクト、1 つを作成し、ソリューションに追加します。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.

17 の ISO オプション

そのプロジェクトを右クリックし、コンテキスト メニューを選択、 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 ValueValue
ローカルのコピーします。Copy local TrueTrue
ローカル サテライト アセンブリをコピーします。Copy Local Satellite Assemblies TrueTrue
参照アセンブリの出力Reference Assembly Output TrueTrue
ライブラリ依存関係のリンクLink Library Dependencies FalseFalse
リンク ライブラリの依存関係の入力Link Library Dependency Inputs FalseFalse

パッケージ プロジェクトを構成します。Configure the packaging project

パッケージ プロジェクトで、 [アプリケーション] フォルダーを右クリックして [参照の追加] を選びます。In the packaging project, right-click the Applications folder, and then choose Add Reference.

プロジェクト参照の追加

PSF ランチャー プロジェクトと、デスクトップ アプリケーション プロジェクトを選択し、選択、 OKボタンをクリックします。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.

配列Array keykey ValueValue
applicationsapplications idid 値を使用して、Idの属性、Applicationパッケージ マニフェスト内の要素。Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications 実行可能ファイル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.
applicationsapplications 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 構成config (省略可能)フィックス アップ 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. つまり、1 つ以上のアプリケーション、プロセス、および DLL のフィックス アップを指定する config.json ファイルを使用することができます。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. 対象のデスクトップ アプリケーションをデバッグするには、手動で選択してデスクトップ アプリケーションのプロセスにアタッチする必要がありますデバッグ->プロセスにアタッチ、アプリケーションを選択プロセスです。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 アプリケーションのデバッグを許可するには、(混在モードのデバッグ) のマネージ コードとネイティブ コードの種類を選択します。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.

注意

Visual Studio では、最も簡単な開発エクスペリエンスをデバッグするには、いくつかの制限があると、このガイドの後で取り上げます他のデバッグ手法を適用することができます。While Visual Studio gives you the simplest development and debugging experience, there are some limitations, so later in this guide, we'll discuss other debugging techniques that you can apply.

ランタイム修正プログラムを作成します。Create a runtime fix

ない場合、ランタイムを解決することは、置換関数を作成し、構成データを含む新しいランタイム修正プログラムを作成することができます、問題の修正は合理的です。If there isn't yet a runtime fix for the issue that you want to resolve, you can create a new runtime fix by writing replacement functions and including any configuration data that makes sense. 各部分を見てみましょう。Let's look at each part.

置換関数Replacement functions

まず、MSIX コンテナーで、アプリケーションの実行時に呼び出しが失敗する関数を特定します。First, identify which function calls fail when your application runs in an MSIX container. 次に、代わりに、ランタイム マネージャーを置換関数を作成できます。Then, you can create replacement functions that you'd like the runtime manager to call instead. これにより、最新のランタイム環境の規則に準拠した動作で、関数の実装を置き換えることです。This gives you an opportunity to replace the implementation of a function with behavior that conforms to the rules of the modern runtime environment.

Visual Studio で、このガイドの前半で作成したランタイム修正プロジェクトを開きます。In Visual Studio, open the runtime fix project that you created earlier in this guide.

宣言、FIXUP_DEFINE_EXPORTSマクロの include ステートメントを追加し、fixup_framework.hそれぞれの上部にあります。CPP ファイルは、ランタイム修正プログラムの機能を追加します。Declare the FIXUP_DEFINE_EXPORTS macro and then add a include statement for the fixup_framework.h at the top of each .CPP file where you intend to add the functions of your runtime fix.

#define FIXUP_DEFINE_EXPORTS
#include <fixup_framework.h>

重要

必ず、 FIXUP_DEFINE_EXPORTS include ステートメントの前にマクロが表示されます。Make sure that the FIXUP_DEFINE_EXPORTS macro appears before the include statement.

同じ関数のシグネチャを持つ関数を作成したが動作を変更します。Create a function that has the same signature of the function who's behavior you want to modify. 置換する関数の例を次に示します、MessageBoxW関数。Here's an example function that replaces the MessageBoxW function.

auto MessageBoxWImpl = &::MessageBoxW;
int WINAPI MessageBoxWFixup(
    _In_opt_ HWND hwnd,
    _In_opt_ LPCWSTR,
    _In_opt_ LPCWSTR caption,
    _In_ UINT type)
{
    return MessageBoxWImpl(hwnd, L"SUCCESS: This worked", caption, type);
}

DECLARE_FIXUP(MessageBoxWImpl, MessageBoxWFixup);

呼び出しDECLARE_FIXUPマップ、MessageBoxW関数を新しい置換する関数。The call to DECLARE_FIXUP maps the MessageBoxW function to your new replacement function. アプリケーションが呼び出すしようとしたときに、MessageBoxW関数を置換する関数を代わりに呼び出すことがされます。When your application attempts to call the MessageBoxW function, it will call the replacement function instead.

修正をランタイムに関数への再帰呼び出しから保護します。Protect against recursive calls to functions in runtime fixes

必要に応じて適用することができます、reentrancy_guard修正をランタイムに関数への再帰呼び出しから保護する、関数への型。You can optionally apply the reentrancy_guard type to your functions that protect against recursive calls to functions in runtime fixes.

たとえば、置換するための関数を生じる可能性があります、CreateFile関数。For example, you might produce a replacement function for the CreateFile function. 実装を呼び出すことができます、CopyFile関数がの実装、CopyFile関数を呼び出すことができます、CreateFile関数。Your implementation might call the CopyFile function, but the implementation of the CopyFile function might call the CreateFile function. 呼び出しの無限の再帰的なサイクルが生じる、CreateFile関数。This may lead to an infinite recursive cycle of calls to the CreateFile function.

詳細についてはreentrancy_guardを参照してくださいauthoring.mdFor more information on reentrancy_guard see authoring.md

構成データConfiguration data

構成データ、ランタイム修正プログラムを追加する場合に追加することを検討してください、config.jsonします。If you want to add configuration data to your runtime fix, consider adding it to the config.json. これでが使用できる、FixupQueryCurrentDllConfigを簡単にそのデータを解析します。That way, you can use the FixupQueryCurrentDllConfig to easily parse that data. この例では、その構成ファイルからのブール値、および文字列の値を解析します。This example parses a boolean and string value from that configuration file.

if (auto configRoot = ::FixupQueryCurrentDllConfig())
{
    auto& config = configRoot->as_object();

    if (auto enabledValue = config.try_get("enabled"))
    {
        g_enabled = enabledValue->as_boolean().get();
    }

    if (auto logPathValue = config.try_get("logPath"))
    {
        g_logPath = logPathValue->as_string().wstring();
    }
}

その他のデバッグ技術Other debugging techniques

Visual Studio は、最も簡単な開発およびデバッグ エクスペリエンスをでは、中にいくつかの制限があります。While Visual Studio gives you the simplest development and debugging experience, there are some limitations.

.Msix からインストールするのではなく、パッケージ レイアウト フォルダーのパスから圧縮しないファイルを展開して、アプリケーションを最初に、F5 デバッグ実行/.appx パッケージ。First, 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 を使用して、f5 キーではなく、.appx パッケージの配置は、ファイルの配置を疎/。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 手法では、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.

子プロセスとしてターゲット アプリケーションの起動をデバッグするには、開始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 ...

注意

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 によって提供されるようになりました direct サポートよりも複雑です。However, it is more complex to use than the direct support now provided by WinDbg.

サポートSupport

ご質問がある場合は、Have questions? 尋ね、パッケージ サポート フレームワークMSIX tech コミュニティ サイトのメッセージ交換の領域。Ask us on the Package Support Framework conversation space on the MSIX tech community site.