From 6b307639132279047ebaa1083037a4a8f8e1c936 Mon Sep 17 00:00:00 2001 From: Kevin Gosse Date: Tue, 25 Nov 2025 10:23:34 +0100 Subject: [PATCH 1/2] Mpgo documentation uses the wrong type of dashes --- ...anaged-profile-guided-optimization-tool.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md index 8b483cd29b29b..b91d31960b213 100644 --- a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md +++ b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md @@ -25,13 +25,13 @@ Enter the following command at the command prompt: For desktop apps: ```console -mpgo –Scenario [-Import ] –AssemblyList ... -OutDir [options] +mpgo -Scenario [-Import ] -AssemblyList ... -OutDir [options] ``` For Windows 8.x Store apps: ```console -mpgo –Scenario -AppID -Timeout +mpgo -Scenario -AppID -Timeout ``` ## Parameters @@ -39,11 +39,11 @@ mpgo –Scenario -AppID -Timeout All arguments to Mpgo.exe are case-insensitive. Commands are prefixed with a dash. > [!NOTE] -> You can use either `–Scenario` or `–Import` as a required command, but not both. None of the required parameters are used if you specify the `–Reset` option. +> You can use either `-Scenario` or `-Import` as a required command, but not both. None of the required parameters are used if you specify the `-Reset` option. |Required parameter|Description| |------------------------|-----------------| -|`-Scenario` \<*command*>

—or—

`-Scenario` \<*packageName*>

-or-

`-Import` \<*directory*>|For desktop apps, use `–Scenario` to specify the command to run the application you want to optimize, including any command-line arguments. Use three sets of double quotation marks around *command* if it specifies a path that includes spaces; for example: `mpgo.exe -scenario """C:\My App\myapp.exe""" -assemblylist """C:\My App\myapp.exe""" -outdir "C:\optimized files"`. Do not use double quotation marks; they will not work correctly if *command* includes spaces.

-or-

For Windows 8.x Store apps, use `–Scenario` to specify the package that you want to generate profile information for. If you specify the package display name or the package family name instead of the full package name, Mpgo.exe will select the package that matches the name you provided if there is only one match. If multiple packages match the specified name, Mpgo.exe will prompt you to choose a package.

—or—

Use `-Import` to specify that optimization data from previously optimized assemblies should be used to optimize the assemblies in `-AssemblyList`. *directory* specifies the directory that contains the previously optimized files. The assemblies specified in `–AssemblyList` or `–AssemblyListFile` are the new versions of the assemblies to be optimized using the data from the imported files. Using optimization data from older version of assemblies enables you to optimize newer versions of assemblies without re-running the scenario. However, if the imported and target assemblies include significantly different code, the optimization data will be ineffective. The assembly names specified in `–AssemblyList` or `–AssemblyListFile` must be present in the directory specified by `–Import`*directory*. Use three sets of double quotation marks around *directory* if it specifies a path that includes spaces.

You must specify either `–Scenario` or `–Import`, but not both parameters.| +|`-Scenario` \<*command*>

—or—

`-Scenario` \<*packageName*>

-or-

`-Import` \<*directory*>|For desktop apps, use `-Scenario` to specify the command to run the application you want to optimize, including any command-line arguments. Use three sets of double quotation marks around *command* if it specifies a path that includes spaces; for example: `mpgo.exe -scenario """C:\My App\myapp.exe""" -assemblylist """C:\My App\myapp.exe""" -outdir "C:\optimized files"`. Do not use double quotation marks; they will not work correctly if *command* includes spaces.

-or-

For Windows 8.x Store apps, use `-Scenario` to specify the package that you want to generate profile information for. If you specify the package display name or the package family name instead of the full package name, Mpgo.exe will select the package that matches the name you provided if there is only one match. If multiple packages match the specified name, Mpgo.exe will prompt you to choose a package.

—or—

Use `-Import` to specify that optimization data from previously optimized assemblies should be used to optimize the assemblies in `-AssemblyList`. *directory* specifies the directory that contains the previously optimized files. The assemblies specified in `-AssemblyList` or `-AssemblyListFile` are the new versions of the assemblies to be optimized using the data from the imported files. Using optimization data from older version of assemblies enables you to optimize newer versions of assemblies without re-running the scenario. However, if the imported and target assemblies include significantly different code, the optimization data will be ineffective. The assembly names specified in `-AssemblyList` or `-AssemblyListFile` must be present in the directory specified by `-Import`*directory*. Use three sets of double quotation marks around *directory* if it specifies a path that includes spaces.

You must specify either `-Scenario` or `-Import`, but not both parameters.| |`-OutDir` \<*directory*>|The directory in which to place the optimized assemblies. If an assembly already exists in the output directory folder, a new copy is created and an index number is appended to its name; for example: *assemblyname*-1.exe. Use double quotation marks around *directory* if it specifies a path that contains spaces.| |`-AssemblyList` \<*assembly1 assembly2 ...*>

—or—

`-AssemblyListFile` \<*file*>|A list of assemblies (including .exe and .dll files), separated by spaces, that you want collect profile information about. You can specify `C:\Dir\*.dll` or `*.dll` to select all the assemblies in the designated or current working directory. See the Remarks section for more information.

—or—

A text file that contains the list of assemblies you want to collect profile information about, listed one assembly per line. If an assembly name begins with a hyphen (-), use an assembly file list or rename the assembly.| |`-AppID` \<*appId*>|The ID of the application in the specified package. If you use the wildcard (\*), Mpgo.exe will try to enumerate the AppIDs in the package and will fall back to \<*package_family_name*>!App if it fails. If you specify a string that is prefixed by an exclamation point (!), Mpgo.exe will concatenate the package family name with the argument provided.| @@ -56,12 +56,12 @@ mpgo –Scenario -AppID -Timeout |`-f`|Forces the inclusion of the profile data in a binary assembly, even if it's signed. If the assembly is signed, it must be re-signed; otherwise, the assembly will fail to load and run.| |`-Reset`|Resets the environment to make certain that an aborted profiling session doesn't affect your assemblies, and then quits. The environment is reset by default before and after a profiling session.| |`-Timeout` \<*time in seconds*>|Specifies the profiling duration in seconds. Use a value that is slightly more than your observed startup times for GUI applications. At the end of the time-out period, the profile data is recorded although the application continues to run. If you don't set this option, profiling will continue until application shutdown, at which time the data will be recorded.| -|`-LeaveNativeImages`|Specifies that the instrumented native images shouldn't be removed after running the scenario. This option is primarily used when you're getting the application that you specified for the scenario running. It will prevent the recreation of native images for subsequent runs of Mpgo.exe. When you have finished running your application, there may be orphaned native images in the cache if you specify this option. In this case, run Mpgo.exe with the same scenario and assembly list and use the `–RemoveNativeImages` parameter to remove these native images.| -|`-RemoveNativeImages`|Cleans up from a run where `–LeaveNativeImages` was specified. If you specify `-RemoveNativeImages`, Mpgo.exe ignores any arguments except `-64bit` and `–AssemblyList`, and exits after removing all instrumented native images.| +|`-LeaveNativeImages`|Specifies that the instrumented native images shouldn't be removed after running the scenario. This option is primarily used when you're getting the application that you specified for the scenario running. It will prevent the recreation of native images for subsequent runs of Mpgo.exe. When you have finished running your application, there may be orphaned native images in the cache if you specify this option. In this case, run Mpgo.exe with the same scenario and assembly list and use the `-RemoveNativeImages` parameter to remove these native images.| +|`-RemoveNativeImages`|Cleans up from a run where `-LeaveNativeImages` was specified. If you specify `-RemoveNativeImages`, Mpgo.exe ignores any arguments except `-64bit` and `-AssemblyList`, and exits after removing all instrumented native images.| ## Remarks - You can use both `–AssemblyList` and `- AssemblyListFile` multiple times on the command line. + You can use both `-AssemblyList` and `- AssemblyListFile` multiple times on the command line. If you do not specify full path names when specifying assemblies, Mpgo.exe looks in the current directory. If you specify an incorrect path, Mpgo.exe displays an error message but continues to generate data for other assemblies. If you specify an assembly that is not loaded during the training scenario, no training data is generated for that assembly. @@ -78,19 +78,19 @@ mpgo –Scenario -AppID -Timeout 2. Run Mpgo.exe as an administrator with the necessary parameters. See the next section for sample commands. - The optimized intermediate language (IL) assemblies are created in the folder specified by the `–OutDir` parameter (in the examples, this is the `C:\Optimized` folder). + The optimized intermediate language (IL) assemblies are created in the folder specified by the `-OutDir` parameter (in the examples, this is the `C:\Optimized` folder). -3. Replace the IL assemblies you used for Ngen.exe with the new IL assemblies that contain the profile information from the directory specified by `–OutDir`. +3. Replace the IL assemblies you used for Ngen.exe with the new IL assemblies that contain the profile information from the directory specified by `-OutDir`. 4. The application setup (using the images provided by Mpgo.exe) will install optimized native images. ## Suggested Workflow -1. Create a set of optimized IL assemblies by using Mpgo.exe with the `–Scenario` parameter. +1. Create a set of optimized IL assemblies by using Mpgo.exe with the `-Scenario` parameter. 2. Check the optimized IL assemblies into source control. -3. In the build process, call Mpgo.exe with the `–Import` parameter as a post-build step to generate optimized IL images to pass to Ngen.exe. +3. In the build process, call Mpgo.exe with the `-Import` parameter as a post-build step to generate optimized IL images to pass to Ngen.exe. This process ensures that all assemblies have optimization data. If you check in updated optimized assemblies (steps 1 and 2) more frequently, the performance numbers will be more consistent throughout product development. @@ -98,9 +98,9 @@ mpgo –Scenario -AppID -Timeout You can run Mpgo.exe from Visual Studio (see the article [How to: Specify Build Events (C#)](/visualstudio/ide/how-to-specify-build-events-csharp)) with the following restrictions: -- You cannot use quoted paths with trailing slash marks, because Visual Studio macros also use trailing slash marks by default. (For example, `–OutDir "C:\Output Folder\"` is invalid.) To work around this restriction, you can escape the trailing slash. (For example, use `-OutDir "$(OutDir)\"` instead.) +- You cannot use quoted paths with trailing slash marks, because Visual Studio macros also use trailing slash marks by default. (For example, `-OutDir "C:\Output Folder\"` is invalid.) To work around this restriction, you can escape the trailing slash. (For example, use `-OutDir "$(OutDir)\"` instead.) -- By default, Mpgo.exe is not on the Visual Studio build path. You must either add the path to Visual Studio or specify the full path on the Mpgo command line. You can use either the `–Scenario` or the `–Import` parameter in the post-build event in Visual Studio. However, the typical process is to use `–Scenario` one time from a Developer Command Prompt for Visual Studio, and then use `–Import` to update the optimized assemblies after each build; for example: `"C:\Program Files\Microsoft Visual Studio 11.0\Team Tools\Performance Tools\mpgo.exe" -import "$(OutDir)tmp" -assemblylist "$(TargetPath)" -outdir "$(OutDir)\"`. +- By default, Mpgo.exe is not on the Visual Studio build path. You must either add the path to Visual Studio or specify the full path on the Mpgo command line. You can use either the `-Scenario` or the `-Import` parameter in the post-build event in Visual Studio. However, the typical process is to use `-Scenario` one time from a Developer Command Prompt for Visual Studio, and then use `-Import` to update the optimized assemblies after each build; for example: `"C:\Program Files\Microsoft Visual Studio 11.0\Team Tools\Performance Tools\mpgo.exe" -import "$(OutDir)tmp" -assemblylist "$(TargetPath)" -outdir "$(OutDir)\"`. @@ -109,13 +109,13 @@ mpgo –Scenario -AppID -Timeout The following Mpgo.exe command from a Developer Command Prompt for Visual Studio optimizes a tax application: ```console -mpgo –scenario "C:\MyApp\MyTax.exe /params par" –AssemblyList Mytax.dll MyTaxUtil2011.dll –OutDir C:\Optimized –TimeOut 15 +mpgo -scenario "C:\MyApp\MyTax.exe /params par" -AssemblyList Mytax.dll MyTaxUtil2011.dll -OutDir C:\Optimized -TimeOut 15 ``` The following Mpgo.exe command optimizes a sound application: ```console -mpgo –scenario "C:\MyApp\wav2wma.exe –input song1.wav –output song1.wma" –AssemblyList transcode.dll –OutDir C:\Optimized –TimeOut 15 +mpgo -scenario "C:\MyApp\wav2wma.exe -input song1.wav -output song1.wma" -AssemblyList transcode.dll -OutDir C:\Optimized -TimeOut 15 ``` The following Mpgo.exe command uses data from previously optimized assemblies to optimize newer versions of the assemblies: From 8f19e3cac18d59012de671214f1f63aed597fa02 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 25 Nov 2025 06:31:57 -0800 Subject: [PATCH 2/2] Update docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md --- .../tools/mpgo-exe-managed-profile-guided-optimization-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md index b91d31960b213..3275ba4c2c538 100644 --- a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md +++ b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md @@ -61,7 +61,7 @@ mpgo -Scenario -AppID -Timeout ## Remarks - You can use both `-AssemblyList` and `- AssemblyListFile` multiple times on the command line. + You can use both `-AssemblyList` and `-AssemblyListFile` multiple times on the command line. If you do not specify full path names when specifying assemblies, Mpgo.exe looks in the current directory. If you specify an incorrect path, Mpgo.exe displays an error message but continues to generate data for other assemblies. If you specify an assembly that is not loaded during the training scenario, no training data is generated for that assembly.