Infrastructure de prise en charge des packages-correction des autorisations d’écriture du système de fichiersPackage Support Framework - Filesystem Write Permission fixup

ExamenInvestigation

Les applications Windows redirigent des répertoires spécifiques liés à l’application vers le dossier de conteneur d’application Windows.Windows Apps will redirect specific directories that are related to the application to the Windows App container folder. Si une application tente d’écrire dans le conteneur d’application Windows, une erreur se déclenche et l’écriture échoue.If an application attempts to write to the Windows App container, an error will trigger, and the write will fail.

À l’aide de l’infrastructure de prise en charge des packages, des améliorations peuvent être apportées au package d’application Windows pour résoudre ce problème.Using the Package Support Framework (PSF), enhancements can be made to the Windows App package to resolve this issue. Tout d’abord, nous devons identifier l’échec, ainsi que les chemins d’accès aux répertoires demandés par l’application.First, we must identify the failure, and directory paths that are being requested by the app.

Capturer l’échec de l’application WindowsCapture the Windows App Failure

Le filtrage des résultats est une étape facultative, qui facilite l’affichage des échecs liés aux applications.Filtering the results is an optional step, that will make viewing application related failures easier. Pour ce faire, nous allons créer deux règles de filtre.To do this, we will create two filter rules. Le premier filtre include pour le nom de processus d’application et le second est une inclusion de résultats qui ne réussissent pas.The first an include filter for the application process name, and the second is an inclusion of any results that are not successful.

  1. Téléchargez et extrayez Sysinternals process Monitor dans le répertoire C:\PSF\ProcessMonitorDownload and extract the SysInternals Process Monitor to the C:\PSF\ProcessMonitor directory.
  2. Ouvrez l’Explorateur Windows et accédez au dossier SysInternals process Monitor extrait.Open Windows Explorer and navigate to the extracted SysInternals Process Monitor Folder
  3. Double-cliquez sur le fichier SysInternals process Monitor (procmon.exe), lancement de l’application.Double-click the SysInternals Process Monitor (procmon.exe) file, launching the app.
  4. Si le contrôle de compte d’utilisateur vous y invite, sélectionnez le bouton Oui .If prompted by UAC, select the Yes button.
  5. Dans la fenêtre filtre du moniteur de processus, sélectionnez le premier menu déroulant intitulé avec architecture.In the Process Monitor Filter Window, select the first drop-down menu labeled with Architecture.
  6. Dans le menu déroulant, sélectionnez nom du processus .Select Process Name from the drop-down menu.
  7. Dans le menu déroulant suivant, vérifiez qu’il est défini avec la valeur de.In the next drop-down menu, verify that it is set with the value of is.
  8. Dans le champ texte, tapez le nom du processus de votre application (exemple : PSFSample.exe).In the text field type the process name of your App (Example: PSFSample.exe). Exemple de fenêtre Filtrer le moniteur de processus avec le nom de l’application
  9. Sélectionnez le bouton Ajouter.Select the Add button.
  10. Dans la fenêtre filtre du moniteur de processus, sélectionnez le premier menu déroulant intitulé traiter le nom du processus.In the Process Monitor Filter Window, select the first drop-down menu labeled Process Name.
  11. Dans le menu déroulant, sélectionnez résultat .Select Result from the drop-down menu.
  12. Dans le menu déroulant suivant, sélectionnez-le et sélectionnez ne figure pas dans le menu déroulant.In the next drop-down menu, select it, and select is not from the drop-down menu.
  13. Dans le champ de texte type : Success.In the text field type: SUCCESS. Exemple de fenêtres filtrer le moniteur de processus avec résultat
  14. Sélectionnez le bouton Ajouter.Select the Add button.
  15. Sélectionnez le bouton OK .Select the Ok button.
  16. Lancez l’application Windows, déclenchez l’erreur et fermez l’application Windows.launch the Windows App, trigger the error, and close the Windows App.

Examiner les journaux d’échec des applications WindowsReview the Windows App Failure Logs

Après avoir capturé les processus d’application Windows, vous devez examiner les résultats pour déterminer si l’échec est lié au répertoire de travail.After capturing the Windows App processes, the results will need to be investigated to identify if the failure is related to the working directory.

  1. Examinez les résultats de l’analyseur SysInternals process Monitor, en recherchant les échecs décrits dans le tableau ci-dessus.Review the SysInternals Process Monitor results, searching for failures outlined in the above table.
  2. Si les résultats affichent un résultat « nom introuvable » , avec les détails « accès souhaité :... » pour votre application spécifique ciblant un répertoire en dehors de « C:\Program Files\WindowsApps \ ... \ » (comme indiqué dans l’image ci-dessous), vous avez correctement identifié une défaillance liée au répertoire de travail, utilisez l’article support des fibres discontinues -système d’exploitation pour obtenir des conseils sur la façon d’appliquer la correction de fibres discontinues à votre application.If the results show an "Name Not Found" result, with the details "Desired Access: ..." for your specific app targeting a directory outside of the "C:\Program Files\WindowsApps\...\" (as seen in the below image), then you have successfully identified a failure related with the working directory, use the PSF Support - Filesystem Access article for guidance on how to apply the PSF correction to your app. Affiche le message d’erreur que vous avez témoin dans SysInternals process Monitor pour l’échec d’écriture dans l’annuaire.

RésolutionResolution

Les applications Windows redirigent des répertoires spécifiques liés à l’application vers le dossier de conteneur d’application Windows.Windows Apps will redirect specific directories that are related to the application to the Windows App container folder. Si une application tente d’écrire dans le conteneur d’application Windows, une erreur se déclenche et l’écriture échoue.If an application attempts to write to the Windows App container, an error will trigger, and the write will fail.

Pour résoudre le problème lié à l’échec de l’écriture de l’application Windows dans le conteneur d’application Windows, nous devons suivre les quatre étapes suivantes :To resolve the issue related to the Windows App failing to write to the Windows App container, we must follow the following four steps:

  1. Déployer l’application Windows dans un répertoire localStage the Windows App to a local directory
  2. Créer le Config.jssur et injecter les fichiers de fibres discontinues requisCreate the Config.json and inject required PSF Files
  3. Mettre à jour le fichier AppxManifest de l’application WindowsUpdate the Windows App AppxManifest file
  4. Reconditionner et signer l’application WindowsRepackage and sign the Windows App

Les étapes ci-dessus fournissent des conseils pour extraire le contenu de l’application Windows dans un répertoire local intermédiaire, en injectant les fichiers de correction des fibres discontinues dans le répertoire des applications Windows intermédiaires, en configurant le lanceur d’applications pour qu’il pointe vers le lanceur de fibres discontinues, puis en configurant les fibres discontinues config.jssur le fichier pour redirigerThe above steps provide guidance through extracting the content of the Windows App to a local staged directory, injecting the PSF fixup files into the staged Windows App directory, configuring the Application Launcher to point to the PSF launcher, then configuring the PSF config.json file to redirect the PSF launcher to the app specifying the working directory.

Télécharger et installer les outils requisDownload and Install Required Tools

Ce processus vous guide tout au long de la récupération et de l’utilisation des outils suivants :This process will guide you through the retrieval of, and usage of the following tools:

  • Outil client NuGetNuGet Client Tool
  • Framework de prise en charge de packagePackage Support Framework
  • SDK Windows 10 (dernière version)Windows 10 SDK (latest version)
  • Analyseur de processus SysInternalsSysInternals Process Monitor

Les éléments suivants fournissent des instructions pas à pas sur le téléchargement et l’installation des outils requis.The following will provide step-by-step guidance on downloading and installing the required tools.

  1. Téléchargez la version la plus récente (sans version préliminaire) de l' outil client NuGet, puis enregistrez le nuget.exe dans le C:\PSF\nuget dossier.Download the latest (non-preview) version of the NuGet client tool, and save the nuget.exe in the C:\PSF\nuget folder.

  2. Téléchargez l’infrastructure de prise en charge du package à l’aide de NuGet en exécutant la commande suivante à partir d’une fenêtre PowerShell d’administration :Download the Package Support Framework using Nuget by running the following from an Administrative PowerShell window:

    Set-Location "C:\PSF"
    .\nuget\nuget.exe install Microsoft.PackageSupportFramework
    
  3. Téléchargez et installez le kit de développement logiciel (SDK) Windows 10 (Win 10 SDK).Download and install the Windows 10 Software Development Toolkit (Win 10 SDK).

    1. Téléchargez le Kit de développement logiciel (SDK) Win 10.Download the Win 10 SDK.
    2. Exécutez le winsdksetup.exe qui a été téléchargé à l’étape précédente.Run the winsdksetup.exe that was downloaded in the previous step.
    3. Sélectionnez le bouton Suivant.Select the Next button.
    4. Sélectionnez uniquement les trois fonctionnalités suivantes pour l’installation :Select only the following three features for install:
      • Outils de signature SDK Windows pour les applications de bureauWindows SDK Signing Tools for Desktop Apps
      • SDK Windows pour les applications C++ UWPWindows SDK for UWP C++ Apps
      • Microsoft SDK pour la localisation d’applications UWPWindwos SDK for UWP Apps Localization
    5. Sélectionnez le bouton Installer.Select the Install button.
    6. Sélectionnez le bouton OK .Select the Ok button.

Déployer l’application WindowsStage the Windows App

En mettant l’application Windows en attente, nous allons extraire/décompresser le contenu de l’application Windows dans un répertoire local.By staging the Windows App, we will be extracting / unpackaging the contents of the Windows App to a local directory. Une fois l’application Windows décompressée dans l’emplacement intermédiaire, les fichiers de correction des fibres discontinues peuvent être injectés en corrigeant les expériences indésirables.Once the Windows App has been unpacked to the staging location, PSF fixup files can be injected correcting any unwanted experiences.

  1. Ouvrez une fenêtre PowerShell d’administration.Open an Administrative PowerShell window.

  2. Définissez les variables suivantes ciblant votre fichier d’application spécifique et la version du kit de développement logiciel (SDK) Windows 10 :Set the following variables targeting your specific app file, and Windows 10 SDK version:

    $AppPath          = "C:\PSF\SourceApp\PSFSampleApp.msix"         ## Path to the MSIX App Installer
    $StagingFolder    = "C:\PSF\Staging\PSFSampleApp"                ## Path to where the MSIX App will be staged
    $OSArchitecture   = "x$((gwmi Win32_Processor).AddressWidth)"    ## Operating System Architecture
    $Win10SDKVersion  = "10.0.19041.0"                               ## Latest version of the Win10 SDK
    
  3. Décompressez l’application Windows dans le dossier intermédiaire en exécutant l’applet de commande PowerShell suivante :Unpack the Windows App to the staging folder by running the following PowerShell cmdlet:

    ## Sets the directory to the Windows 10 SDK
    Set-Location "${env:ProgramFiles(x86)}\Windows Kits\10\Bin\$Win10SDKVersion\$OSArchitecture"
    
    ## Unpackages the Windows App to the staging folder
    .\makeappx.exe unpack /p "$AppPath" /d "$StagingFolder"
    

Créer et injecter les fichiers de fibres discontinues nécessairesCreate and inject required PSF Files

Pour appliquer des actions correctives à l’application Windows, un fichierconfig.jsdoit être créé et fourni avec des informations sur le lanceur d' applications Windows qui échouent.To apply corrective actions to the Windows App the a config.json file must be created, and supplied with information about the Windows App Launcher that is failing. Si plusieurs lanceurs d’applications Windows rencontrent des problèmes, le config.jssur le fichier peut être mis à jour avec plusieurs entrées.If there are multiple Windows App Launchers that are experiencing issues, the config.json file can be updated with multiple entries.

Après la mise à jour de l'config.jssur le fichier, les fichiers de correction du config.jssur le fichier et de la prise en charge doivent être déplacés à la racine du package d’application Windows.After updating the config.json file, the config.json file and supporting PSF fixup files must then be moved into the root of the Windows App package.

  1. Ouvrez Visual Studio Code (VS Code) ou tout autre éditeur de texte.Open Visual Studio Code (VS Code), or any other text editor.

  2. Créez un nouveau fichier, en sélectionnant le menu fichier en haut de la vs code, en sélectionnant nouveau fichier dans le menu déroulant.Create a new file, by selecting the File menu at the top of the VS Code, selecting New File from the drop-down menu.

  3. Enregistrez le fichier en tant que config.jssur, en sélectionnant le menu fichier en haut de la fenêtre de vs code, en sélectionnant Enregistrer dans le menu déroulant.Save the file as config.json, by select the File menu at the top of the VS Code window, selecting Save from the drop-down menu. Dans la fenêtre Enregistrer sous, accédez au répertoire intermédiaire des applications Windows (C:\PSF\Staging\PSFSampleApp) et définissez le nom de fichier sur config.json .In the Save As window, navigate to the Windows App Staging directory (C:\PSF\Staging\PSFSampleApp) and set the File Name as config.json. Sélectionnez le bouton Enregistrer.Select the Save button.

  4. Copiez le code suivant dans laconfig.jsnouvellement créée dans le fichier.Copy the following code to the newly created config.json file.

    {
        "applications": [
            {
                "id": "",
                "executable": ""
            }
        ],
        "processes": [
            {
                "executable": "",
                "fixups": [
                {
                    "dll": "",
                    "config": {
                        "redirectedPaths": {
                            "packageRelative": [
                                {
                                    "base": "",
                                    "patterns": [
                                        ""
                                    ]
                                }
                            ]
                        }
                    }
                }
            ]
            }
        ]
    }
    
  5. Ouvrez le fichier AppxManifest de l’application Windows intermédiaire situé dans le dossier intermédiaire des applications windows (C:\PSF\Staging\PSFSampleApp\AppxManifest.xml) à l’aide de vs code ou d’un autre éditeur de texte.Open the staged Windows App AppxManifest file located in the Windows App staging folder (C:\PSF\Staging\PSFSampleApp\AppxManifest.xml) using VS Code, or another text editor.

    <Applications>
        <Application Id="PSFSAMPLE" Executable="VFS\ProgramFilesX64\PS Sample App\PSFSample.exe" EntryPoint="Windows.FullTrustApplication">
        <uap:VisualElements BackgroundColor="transparent" DisplayName="PSFSample" Square150x150Logo="Assets\StoreLogo.png" Square44x44Logo="Assets\StoreLogo.png" Description="PSFSample">
            <uap:DefaultTile Wide310x150Logo="Assets\StoreLogo.png" Square310x310Logo="Assets\StoreLogo.png" Square71x71Logo="Assets\StoreLogo.png" />
        </uap:VisualElements>
        </Application>
    </Applications>
    
  6. Définissez la applications.id valeur de l' config.jssur sur la valeur trouvée dans le champ applications.application.ID du fichier AppxManifest.xml .Set the applications.id value in the config.json to be the same value as found in the Applications.Application.ID field of the AppxManifest.xml file. Image tournant l’emplacement de l’ID dans le fichier AppxManifest.

  7. Définissez la applications.executable valeur dans la config.jssur pour cibler le chemin d’accès relatif à l’application située dans Applications.Application.Exechamp cutable du fichier AppxManifest.xml .Set the applications.executable value in the config.json to target the relative path to the application located in Applications.Application.Executable field of the AppxManifest.xml file. Image tournant l’emplacement de l’exécutable dans le fichier AppxManifest.

  8. Définissez la applications.workingdirectory valeur dans la config.jssur pour cibler le chemin de dossier relatif trouvé dans le champ Applications.Application.Executable du fichier AppxManifest.xml .Set the applications.workingdirectory value in the config.json to target the relative folder path found in the Applications.Application.Executable field of the AppxManifest.xml file. Image tournant l’emplacement du répertoire de travail dans le fichier AppxManifest.

  9. Définissez la process.executable valeur dans la config.jssur pour cibler le nom de fichier (sans chemin d’accès et extensions) trouvé dans le champ Applications.Application.Executable du fichier AppxManifest.xml .Set the process.executable value in the config.json to target the file name (without path and extensions) found in the Applications.Application.Executable field of the AppxManifest.xml file. Image tournant l’emplacement de l’exécutable du processus dans le fichier AppxManifest.

  10. Définissez la processes.fixups.dll valeur dans la config.jssur pour cibler le FileRedirectionFixup.dll spécifique à l’architecture.Set the processes.fixups.dll value in the config.json to target the architecture specific FileRedirectionFixup.dll. Si la correction concerne l’architecture x64, définissez la valeur sur FileRedirectionFixup64.dll.If correction is for x64 architecture, set the value to be FileRedirectionFixup64.dll. Si l’architecture est x86 ou est inconnue, définissez la valeur sur FileRedirectionFixup86.dllIf the architecture is x86, or is unknown, set the value to be FileRedirectionFixup86.dll

  11. Définissez la processes.fixups.config.redirectedPaths.packageRelative.base valeur de la config.jssur le chemin d’accès au dossier relatif du package, tel qu’indiqué dans le Applications.Application.Executable du fichier AppxManifest.xml .Set the processes.fixups.config.redirectedPaths.packageRelative.base value in the config.json to the package relative folder path as found in the Applications.Application.Executable of the AppxManifest.xml file. Image tournant l’emplacement du répertoire de travail dans le fichier AppxManifest.

  12. Définissez la processes.fixups.config.redirectedPaths.packageRelative.patterns valeur dans le fichier config.js pour qu’elle corresponde au type de fichier créé par l’application.Set the processes.fixups.config.redirectedPaths.packageRelative.patterns value in the config.json file to match the file type being created by the application. En utilisant « . * \ . log » , les fibres discontinues redirigent les écritures de tous les fichiers journaux qui se trouvent dans le répertoire identifié dans le chemin d’accès processes.fixups.config. redirectedPaths. packageRelative. base , ainsi que les répertoires enfants.By using ".*\.log" the PSF will redirect writes for all log files that are in the directory identified in the processes.fixups.config.redirectedPaths.packageRelative.base path, as well as child directories.

  13. Enregistrez leconfig.jsmis à jour dans le fichier.Save the updated config.json file.

    {
        "applications": [
            {
            "id": "PSFSample",
            "executable": "VFS/ProgramFilesX64/PS Sample App/PSFSample.exe"
            }
        ],
        "processes": [
            {
                "executable": "PSFSample",
                "fixups": [
                    {
                        "dll": "FileRedirectionFixup64.dll",
                        "config": {
                            "redirectedPaths": {
                                "packageRelative": [
                                    {
                                        "base": "VFS/ProgramFilesX64/PS Sample App/",
                                        "patterns": [
                                            ".*\\.log"
                                        ]
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        ]
    }
    
  14. Copiez les quatre fichiers suivants à partir de l’infrastructure de prise en charge des packages, en fonction de l’architecture exécutable de l’application, à la racine de l’application Windows intermédiaire.Copy the following four files from the Package Support Framework based on the application executable architecture to the root of the staged Windows App. Les fichiers suivants se trouvent dans le .\Microsoft.PackageSupportFramework. \bin.The following files are located within the .\Microsoft.PackageSupportFramework.\bin.

    Application (x64)Application (x64) Application (x86)Application (x86)
    PSFLauncher64.exePSFLauncher64.exe PSFLauncher32.exePSFLauncher32.exe
    PSFRuntime64.dllPSFRuntime64.dll PSFRuntime32.dllPSFRuntime32.dll
    PSFRunDll64.exePSFRunDll64.exe PSFRunDll32.exePSFRunDll32.exe
    FileRedirectionFixup64.dllFileRedirectionFixup64.dll FileRedirectionFixup64.dllFileRedirectionFixup64.dll

Mettre à jour AppxManifestUpdate AppxManifest

Après la création et la mise à jour de l'config.jssur le fichier, le AppxManifest.xml de l’application Windows doit être mis à jour pour chaque lanceur d’applications windows inclus dans le config.jssur.After creating and updating the config.json file, the Windows App's AppxManifest.xml must be updated for each Windows App Launcher that was included in the config.json. Les applications de AppxManifest doivent maintenant cibler les PSFLauncher.exe associées à l’architecture des applications.The AppxManifest's Applications must now target the PSFLauncher.exe associated with the applications architecture.

  1. Ouvrez l’Explorateur de fichiers et accédez au dossier d’application MSIX intermédiaire (C:\PSF\Staging\PSFSampleApp).Open File Explorer, and navigate to the Staged MSIX App folder (C:\PSF\Staging\PSFSampleApp).

  2. Cliquez avec le bouton droit sur AppxManifest.xml, puis sélectionnez Ouvrir avec du code dans le menu déroulant (si vous le souhaitez, vous pouvez ouvrir avec un autre éditeur de texte).Right-click on AppxManifest.xml, and select Open with Code from the drop-down menu (Optionally, you can open with another text editor).

  3. Mettez à jour le fichier AppxManifest.xml avec les informations suivantes :Update the AppxManifest.xml file with the following information:

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

Recréer le package de l’applicationRe-package the application

Toutes les corrections ont été appliquées, l’application Windows peut désormais être regroupée dans un MSIX et signée à l’aide d’un certificat de signature de code.All of the corrections have been applied, now the Windows App can be re-packaged into an MSIX and signed using a code signing certificate.

  1. Ouvrez une fenêtre PowerShell d’administration.Open an Administrative PowerShell Window.

  2. Définissez les variables suivantes :Set the following variables:

    $AppPath          = "C:\PSF\SourceApp\PSFSampleApp_Updated.msix" ## Path to the MSIX App Installer
    $CodeSigningCert  = "C:\PSF\Cert\CodeSigningCertificate.pfx"     ## Path to your code signing certificate
    $CodeSigningPass  = "<Password>"                                 ## Password used by the code signing certificate
    $StagingFolder    = "C:\PSF\Staging\PSFSampleApp"                ## Path to where the MSIX App will be staged
    $OSArchitecture   = "x$((gwmi Win32_Processor).AddressWidth)"    ## Operating System Architecture
    $Win10SDKVersion  = "10.0.19041.0"                               ## Latest version of the Win10 SDK
    
  3. Recompresser l’application Windows à partir du dossier intermédiaire en exécutant l’applet de commande PowerShell suivante :Repack the Windows App from the staging folder by running the following PowerShell cmdlet:

    Set-Location "${env:ProgramFiles(x86)}\Windows Kits\10\Bin\$Win10SDKVersion\$OSArchitecture"
    .\makeappx.exe pack /p "$AppPath" /d "$StagingFolder"
    
  4. Signez l’application Windows en exécutant l’applet de commande PowerShell suivante :Sign the Windows App by running the following PowerShell cmdlet:

    Set-Location "${env:ProgramFiles(x86)}\Windows Kits\10\Bin\$Win10SDKVersion\$OSArchitecture"
    .\signtool.exe sign /v /fd sha256 /f $CodeSigningCert /p $CodeSigningPass $AppPath