Aplicación del marco de compatibilidad de paquete en Visual StudioApply Package Support Framework in Visual Studio

El marco de soporte de paquetes (PSF) es un proyecto de código abierto que permite aplicar correcciones a la aplicación de escritorio existente.The Package Support Framework (PSF) is an open source project that enables you to apply fixes to your existing desktop application. El PSF permite a una aplicación ejecutarse en un formato empaquetado de MSIX sin modificar el código.The PSF enables an application to run in an MSIX packaged format without modifying code. La plataforma de compatibilidad de paquete te ayuda a que la aplicación siga las prácticas recomendadas del entorno de tiempo de ejecución moderno.The Package Support Framework helps your application follow the best practices of the modern runtime environment.

En las secciones siguientes, veremos cómo crear un nuevo proyecto de Visual Studio, incluir el marco de soporte de paquetes en la solución y crear correcciones en tiempo de ejecución.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.

Paso 1: crear una solución de paquete en Visual StudioStep 1: Create a package solution in Visual Studio

En Visual Studio, cree una nueva solución de Visual Studio soluciones en blanco.In Visual Studio, create a new Visual Studio Solutions, Blank Solution. Incluya cualquier proyecto de aplicación en la solución en blancorecién creada.Include any application projects to the newly created Blank Solution.

Paso 2: agregar un proyecto de empaquetadoStep 2: Add a packaging project

Si aún no tiene un proyecto de paquete de aplicación de Windows, cree uno y agréguelo a la solución.If you don't already have a Windows Application Packaging Project, create one and add it to your solution. Cree un nuevo proyecto de paquete de aplicación de Windows de Windows Universal > de > de Visual C# y agréguelo a la solución recién creada.Create a new Visual C# -> Windows Universal -> Windows Application Packaging Project and add it to your newly created solution.

Para obtener más información sobre el proyecto de paquete de aplicación de Windows, consulte empaquetar la aplicación con Visual Studio.For more information on Windows Application Packaging project, see Package your application by using Visual Studio.

En Explorador de soluciones, haga clic con el botón derecho en el proyecto de empaquetado, seleccione Editary, a continuación, agréguelo a la parte inferior del archivo del proyecto: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)'=='<Runtime fix project name>'" />
  </FilteredNonWapProjProjectOutput>
  <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
  <_FilteredNonWapProjProjectOutput Include="@(FilteredNonWapProjProjectOutput)" />
</ItemGroup>
</Target>

Paso 3: agregar el proyecto para la corrección en tiempo de ejecuciónStep 3: Add project for the runtime fix

Agregue a la solución un nuevo proyecto de la biblioteca de vínculos dinámicos (dll) de > de escritorio de Windows Visual C++ > .Add a new Visual C++ -> Windows Desktop -> Dynamic-Link Library (DLL) project to the solution.

A continuación, haga clic con el botón derecho en el proyecto y elija propiedades.Next, right-click the that project, and then choose Properties.

En la página de propiedades, busque el campo propiedades de configuración-> C/C++-> Language-> C++ Language Standard .In the property page, locate the Configuration Properties -> C/C++ -> Language -> C++ Language Standard field. A continuación, seleccione ISO C++ 17 Standard (/STD: c++ 17) en el menú desplegable.Then select ISO C++17 Standard (/std:c++17) from the drop-down menu.

Haga clic con el botón derecho en el proyecto y, a continuación, en el menú contextual, elija la opción administrar paquetes Nuget .Right-click on the project, and then in the context menu, choose the Manage Nuget Packages option. Asegúrese de que la opción origen del paquete esté establecida en All o Nuget.org.Ensure that the Package source option is set to All or nuget.org.

Haga clic en el icono de configuración situado junto a ese campo.Click the settings icon next that field.

Busque los paquetes de Nuget para PSFy, a continuación, instale Microsoft. PackageSupportFramework para este proyecto.Search the Nuget packages for PSF, then install the Microsoft.PackageSupportFramework for this project.

paquete de nuget

Paso 4: agregar un proyecto que inicia el ejecutable del iniciador PSFStep 4: Add a project that starts the PSF Launcher executable

Agregue un Visual C++ nuevo proyecto vacío > > general a la solución.Add a new Visual C++ -> General -> Empty Project to the solution.

Siga estos pasos:Do the following steps:

  1. Haga clic con el botón derecho en el proyecto y, a continuación, en el menú contextual, elija la opción administrar paquetes Nuget .Right-click that project, and then in the context menu, choose the Manage Nuget Packages option. Asegúrese de que la opción origen del paquete esté establecida en All o Nuget.org.Ensure that the Package source option is set to All or nuget.org.
  2. Haga clic en el icono de configuración situado junto a ese campo.Click the settings icon next that field.
  3. Busque los paquetes de Nuget para PSF y, a continuación, instale Microsoft. PackageSupportFramework para este proyecto.Search the Nuget packages for PSF, then install the Microsoft.PackageSupportFramework for this project.

Abra las páginas de propiedades del proyecto y, en la página configuración General , establezca la propiedad nombre de destino en PSFLauncher32 o en PSFLauncher64 función de la arquitectura de la aplicación.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.

Agregue una referencia de proyecto al proyecto de corrección en tiempo de ejecución de la solución.Add a project reference to the runtime fix project in your solution.

Haga clic con el botón secundario en la referencia y, a continuación, en la ventana propiedades , aplique estos valores.Right-click the reference, and then in the Properties window, apply these values.

PropiedadProperty ValueValue
Copiar localCopy local TrueTrue
Copiar ensamblados satélite localesCopy Local Satellite Assemblies TrueTrue
Salida de ensamblado de referenciaReference Assembly Output TrueTrue
Dependencias de la biblioteca de vínculosLink Library Dependencies FalseFalse
Enlazar entradas de dependencia de bibliotecaLink Library Dependency Inputs FalseFalse

Paso 5: configurar el proyecto de empaquetadoStep 5: Configure the packaging project

Para configurar el proyecto de empaquetado, realice los pasos siguientes:To configure the packaging project do the following steps:

  1. En el proyecto de empaquetado, haga clic con el botón secundario en la carpeta aplicaciones y, a continuación, elija Agregar referencia en el menú desplegable.In the packaging project, right-click the Applications folder, and then choose Add Reference from the dropdown menu.
  2. Elija el proyecto del iniciador PSF y el proyecto de aplicación de escritorio y, a continuación, elija el botón Aceptar .Choose the PSF Launcher project and your desktop application project, and then choose the OK button.
  3. Seleccione el iniciador PSF y el proyecto aplicación de escritorio y, a continuación, haga clic en el botón Aceptar.Select both the PSF Launcher and the Desktop Application project, then click the Ok button. Si el código fuente de la aplicación no está disponible, seleccione solo el proyecto del iniciador PSF.If the application source code is not available, select only the PSF Launcher project.
  4. En el nodo aplicaciones , haga clic con el botón secundario en la aplicación del iniciador PSF y elija establecer como punto de entrada.In the Applications node, right-click the PSF Launcher application, and then choose Set as Entry Point.

Agregue un archivo denominado config.json al proyecto de empaquetado y, después, copie y pegue el siguiente texto JSON en el archivo.Add a file named config.json to your packaging project, then, copy and paste the following json text into the file. Establezca la propiedad acción del paquete en contenido.Set the Package Action property to Content.

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

Proporcione un valor para cada clave.Provide a value for each key. Use esta tabla como guía.Use this table as a guide.

MatrizArray keykey ValueValue
applicationsapplications idid Utilice el valor del Id atributo del Application elemento en el manifiesto del paquete.Use the value of the Id attribute of the Application element in the package manifest.
applicationsapplications ejecutableexecutable La ruta de acceso relativa del paquete al ejecutable que desea iniciar.The package-relative path to the executable that you want to start. En la mayoría de los casos, puede obtener este valor desde el archivo de manifiesto del paquete antes de modificarlo.In most cases, you can get this value from your package manifest file before you modify it. Es el valor del Executable atributo del Application elemento.It's the value of the Executable attribute of the Application element.
applicationsapplications workingDirectoryworkingDirectory Opta Ruta de acceso relativa del paquete que se va a usar como directorio de trabajo de la aplicación que se inicia.(Optional) A package-relative path to use as the working directory of the application that starts. Si no establece este valor, el sistema operativo usará el System32 directorio como directorio de trabajo de la aplicación.If you don't set this value, the operating system uses the System32 directory as the application's working directory.
procesosprocesses ejecutableexecutable En la mayoría de los casos, este será el nombre de la executable configuración anterior con la ruta de acceso y la extensión de archivo que se han quitado.In most cases, this will be the name of the executable configured above with the path and file extension removed.
correccionesfixups dlldll Ruta de acceso relativa del paquete a la DLL de corrección que se va a cargar.Package-relative path to the fixup DLL to load.
correccionesfixups configconfig Opta Controla cómo se comporta el archivo DLL de corrección.(Optional) Controls how the fixup DLL behaves. El formato exacto de este valor varía en función de la corrección por corrección, ya que cada corrección puede interpretar este "BLOB" como se desea.The exact format of this value varies on a fixup-by-fixup basis as each fixup can interpret this "blob" as it wants.

Cuando haya terminado, el config.json archivo tendrá un aspecto similar al siguiente.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" } ]
    }
  ]
}

Nota

Las applications processes claves, y fixups son matrices.The applications, processes, and fixups keys are arrays. Esto significa que puede usar el archivo config. JSON para especificar más de una aplicación, proceso y DLL de corrección.That means that you can use the config.json file to specify more than one application, process, and fixup DLL.

Depurar una corrección en tiempo de ejecuciónDebug a runtime fix

En Visual Studio, presione F5 para iniciar el depurador.In Visual Studio, press F5 to start the debugger. Lo primero que se inicia es la aplicación del iniciador PSF, que, a su vez, inicia la aplicación de escritorio de destino.The first thing that starts is the PSF Launcher application, which in turn, starts your target desktop application. Para depurar la aplicación de escritorio de destino, tendrá que asociarse manualmente al proceso de aplicación de escritorio eligiendo Depurar >adjuntar al procesoy, a continuación, seleccionar el proceso de la aplicación.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. Para permitir la depuración de una aplicación .NET con una DLL de corrección nativa en tiempo de ejecución, seleccione tipos de código administrado y nativo (depuración en modo mixto).To permit the debugging of a .NET application with a native runtime fix DLL, select managed and native code types (mixed mode debugging).

Puede establecer puntos de interrupción junto a líneas de código en el código de aplicación de escritorio y el proyecto de corrección en tiempo de ejecución.You can set break points next to lines of code in the desktop application code and the runtime fix project. Si no tiene el código fuente de la aplicación, podrá establecer puntos de interrupción solo junto a las líneas de código en el proyecto de corrección en tiempo de ejecución.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.