Merge pull request #10363 from MicrosoftDocs/main638598602054320344sy…

…nc_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

docs/extensibility/image-service-and-catalog.md

@@ -1,7 +1,7 @@
 ---
 title: Image Service and Catalog
 description: This article contains guidance and best practices for adopting the Visual Studio Image Service and Image Catalog.
-ms.date: 04/01/2019
+ms.date: 08/21/2024
 ms.topic: conceptual
 author: maiak
 ms.author: maiak
@@ -92,6 +92,8 @@ This cookbook contains guidance and best practices for adopting the Visual Studi
  <Guid Name="ShellCommandGuid" Value="8ee4f65d-bab4-4cde-b8e7-ac412abbda8a" />
  <ID Name="cmdidSaveAll" Value="1000" />
  <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal" />
+ <!-- If your assembly is strongly named, you'll need the version and public key token as well -->
+ <!-- <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal;v17.0.0.0;b03f5f7f11d50a3a" /> -->
 </Symbols>
 ```
 
@@ -682,6 +684,32 @@ b714fcf7-855e-4e4c-802a-1fd87144ccad,2,fda30684-682d-421c-8be4-650a2967058e,200
 
  - Set "Include in VSIX" to True.
 
+- My images are still not working, how do I figure out what's wrong?
+
+ - Visual Studio may not be finding your image manifest. For performance reasons Visual Studio limits folder search depth, so it's recommended that the image manifest be kept in the root folder of your extension.
+
+ - You might be missing assembly information in your image manifest file. Assemblies that are strongly named require additional information in order to be loaded by Visual Studio. In order to load a strongly named assembly, you need to include (in addition to the assembly name) the assembly version and public key token in the resource URIs for the images in your image manifest.
+ ```xml
+ <ImageManifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/VisualStudio/ImageManifestSchema/2014">
+ <Symbols>
+ <String Name="Resources" Value="/Microsoft.VisualStudio.Shell.UI.Internal;v17.0.0.0;b03f5f7f11d50a3a;Component/Resources" />
+ ...
+ </Symbols>
+ ...
+ </ImageManifest>
+ ```
+ - You may be missing a codebase entry for your image assembly. If your assembly is not yet loaded by the time Visual Studio needs it, it will need to know where to find your assembly in order to load it. To add a codebase for your assembly, you can use the ProvideCodeBaseAttribute to ensure a codebase entry is generated and included in your extension's pkgdef.
+ ```csharp
+ [assembly: ProvideCodeBase(AssemblyName = "ClassLibrary1", Version = "1.0.0.0", CodeBase = "$PackageFolder$\\ClassLibrary1.dll")]
+ ```
+ - If the previous options do no resolve your image load issue, you can enable logging by dropping the following entries into a pkgdef in your extension:
+ ```
+ [$RootKey$\ImageLibrary]
+ "TraceLevel"="Verbose"
+ "TraceFilename"="ImageLibrary.log"
+ ```
+ This will create a log file called ImageLibrary.log in your %UserProfile% folder. Make sure to run "devenv /updateConfiguration" from a developer command prompt after adding these entries to a pkgdef. This ensures that the logging entries are enabled and that VS refreshes the image manifest cache to help find any errors that may occur when reading your image manifest. If you then run through the scenario where your image is expected to load, your log file will contain both the registration logging and request logging for your image.
+
 - I am updating my CPS Project System. What happened to **ImageName** and **StockIconService**?
 
  - These were removed when CPS was updated to use monikers. You no longer need to call the **StockIconService**, just pass the desired **KnownMoniker** to the method or property using the **ToProjectSystemType()** extension method in the CPS utilities. You can find a mapping from **ImageName** to **KnownMonikers** below:
@@ -751,7 +779,7 @@ b714fcf7-855e-4e4c-802a-1fd87144ccad,2,fda30684-682d-421c-8be4-650a2967058e,200
  |ImageName.CSharpCodeFile|KnownImageIds.CSFileNode|
  |ImageName.VisualBasicCodeFile|KnownImageIds.VBFileNode|
 
-  - I am updating my completion list provider. What **KnownMonikers** match to the old **StandardGlyphGroup** and **StandardGlyph** values?
+ - I am updating my completion list provider. What **KnownMonikers** match to the old **StandardGlyphGroup** and **StandardGlyph** values?
 
  |Name|Name|Name|
  |-|-|-|

docs/extensibility/internals/image-library-viewer.md

@@ -1,7 +1,7 @@
 ---
 title: Image Library Viewer
 description: Learn about the Visual Studio Image Library Viewer tool that loads and searches image manifests, allowing you to view and manipulate image attributes.
-ms.date: 11/04/2016
+ms.date: 08/21/2024
 ms.topic: reference
 author: maiak
 ms.author: maiak
@@ -59,6 +59,8 @@ A complete image manifest looks like this:
  <Guid Name="ShellCommandGuid" Value="8ee4f65d-bab4-4cde-b8e7-ac412abbda8a" />
  <ID Name="cmdidSaveAll" Value="1000" />
  <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal" />
+ <!-- If your assembly is strongly named, you'll need the version and public key token as well -->
+ <!-- <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal;v17.0.0.0;b03f5f7f11d50a3a" /> -->
 </Symbols>
 ```
 

docs/extensibility/internals/manifest-from-resources.md

@@ -1,7 +1,7 @@
 ---
 title: Manifest from Resources
 description: Learn how to use the Manifest from Resources tool to add .png or .xaml files to an .imagemanifest file for use with the Visual Studio Image Service. 
-ms.date: 11/04/2016
+ms.date: 08/21/2024
 ms.topic: reference
 author: maiak
 ms.author: maiak
@@ -10,7 +10,7 @@ ms.subservice: extensibility-integration
 ---
 # Manifest from Resources
 
-The Manifest from Resources tool is a console application that takes a list of image resources (.png or .xaml files) and generates an .imagemanifest file that allows those images to be used with the Visual Studio Image Service. Additionally, this tool can be used to add images to an existing .imagemanifest. This tool is useful for adding high-DPI and theming support for images to a Visual Studio extension. The generated .imagemanifest file should be included in and deployed as a part of a Visual Studio extension (.vsix).
+The Manifest from Resources tool is a console application that takes a list of image resources (.png or .xaml files). Using that list, it generates an .imagemanifest file that allows those images to be used with the Visual Studio Image Service. Additionally, this tool can be used to add images to an existing .imagemanifest. This tool is useful for adding high-DPI and theming support for images to a Visual Studio extension. The generated .imagemanifest file should be included in and deployed as a part of a Visual Studio extension (.vsix).
 
 ## How to use the tool
  **Syntax**
@@ -21,45 +21,47 @@ The Manifest from Resources tool is a console application that takes a list of i
 
 |**Switch name**|**Notes**|**Required or Optional**|
 |-|-|-|
-|/resources|A semicolon-delimited list of images or directories. This list should always contain the full list of images that will be in the manifest. If only a partial list is given, the entries not included will be lost.<br /><br /> If a given resource file is an image strip, the tool will split it into separate images before adding each subimage to the manifest.<br /><br /> If the image is a .png file, we recommended you format the name like this so that the tool can fill in the right attributes for the image: \<Name>.\<Width>.\<Height>.png.|Required|
-|/assembly|The name of the managed assembly (not including the extension), or the runtime path of the native assembly that hosts the resources (relative to the manifest's runtime location).|Required|
-|/manifest|The name to give to the generated .imagemanifest file. This can also include an absolute or relative path to create the file in a different location. The default name matches the assembly name.<br /><br /> Default: \<Current Directory>\\<Assembly\>.imagemanifest|Optional|
+|/resources|A semicolon-delimited list of images or directories. This list should always contain the full list of images that will be in the manifest. If only a partial list is given, the entries not included will be lost.<br /><br /> If a given resource file is an image strip, the tool splits it into separate images before adding each subimage to the manifest.<br /><br /> If the image is a .png file, we recommended you format the name like this so that the tool can fill in the right attributes for the image: \<Name>.\<Width>.\<Height>.png.|Required|
+|/assembly|The name of the managed assembly (not including the extension), or the runtime path of the native assembly that hosts the resources (relative to the manifest's runtime location). Additionally, if the assembly is strongly named, this entry should include the assembly version and public key token.|Required|
+|/manifest|The name to give to the generated .imagemanifest file. This can also include an absolute or relative path to create the file in a different location. The default name matches the assembly name. Additionally, when providing the extra strong name information in the /assembly switch, this switch should be supplied with a user friendly manifest name so that the assembly strong name information isn't included in the manifest name. <br /><br /> Default: \<Current Directory>\\<Assembly\>.imagemanifest|Optional|
 |/guidName|The name to give to the GUID symbol for all of the images in the generated manifest.<br /><br /> Default: AssetsGuid|Optional|
 |/rootPath|The root path that needs to be stripped off before creating managed resource URIs. (This flag is to help with cases where the tool gets the relative URI path wrong, causing resources to fail to load.)<br /><br /> Default: \<Current Directory>|Optional|
-|/recursive|Setting this flag tells the tool to recursively search any directories in the /resources argument. Omitting this flag will result in a top-level-only search of directories.|Optional|
-|/isNative|Set this flag when the assembly argument is a path for a native assembly. Omit this flag when the assembly argument is the name of a managed assembly. (See the Notes section for additional information about this flag.)|Optional|
+|/recursive|Setting this flag tells the tool to recursively search any directories in the /resources argument. Omitting this flag results in a top-level-only search of directories.|Optional|
+|/isNative|Set this flag when the assembly argument is a path for a native assembly. Omit this flag when the assembly argument is the name of a managed assembly. (For more information about this flag, see the Notes section.)|Optional|
 |/newGuids|Setting this flag tells the tool to create a new value for the images' GUID symbol instead of merging the one from the existing manifest.|Optional|
 |/newIds|Setting this flag tells the tool to create new ID symbol values for every image instead of merging values from the existing manifest.|Optional|
 |/noLogo|Setting this flag stops product and copyright information from printing.|Optional|
-|/?|Print out Help information.|Optional|
-|/help|Print out Help information.|Optional|
+|/?|Prints Help information.|Optional|
+|/help|Prints out Help information.|Optional|
 
  **Examples**
 
-- ManifestFromResources /resources:D:\Images  /assembly:My.Assembly.Name  /isNative
+- ManifestFromResources /resources:D:\Images /assembly:My.Assembly.Name /isNative
 
-- ManifestFromResources /resources:D:\Images\Image1.png;D:\Images\Image1.xaml  /assembly:My.Assembly.Name  /manifest:MyImageManifest.imagemanifest
+- ManifestFromResources /resources:D:\Images\Image1.png;D:\Images\Image1.xaml /assembly:My.Assembly.Name /manifest:MyImageManifest.imagemanifest
 
-- ManifestFromResources /resources:D:\Images\Image1.png;D:\Images\Image1.xaml /assembly:My.Assembly.Name /guidName:MyImages /newGuids /newIds
+- ManifestFromResources /resources:D:\Images\Image1.png;D:\Images\Image1.xaml /assembly:My.Assembly.Name;v1.0.0.0;abcdef0123456789 /manifest:MyImageManifest.imagemanifest
+
+- ManifestFromResources /resources:D:\Images\Image1.png;D:\Images\Image1.xaml /assembly:My.Assembly.Name /guidName:MyImages /newGuids /newIds
 
 ## Notes
 
-- The tool only supports .png and .xaml files. Any other image or file types will be ignored. A warning is generated for all unsupported types encountered while parsing the resources. If no supported images are found when the tool is finished parsing the resources, an error will be generated
+- The tool only supports .png and .xaml files. Any other image or file types are ignored. A warning is generated for all unsupported types encountered while parsing the resources. If no supported images are found when the tool is finished parsing the resources, an error is generated
 
-- By following the suggested format for .png images, the tool will set the size/dimension value for the .png to the format-specified size, even if it differs from the image's actual size.
+- Following the suggested format for .png images results in the tool setting the size/dimension value for the .png to the format-specified size, even if it differs from the image's actual size.
 
 - The width/height format can be omitted for .png images, but the tool will read the image's actual width/height and use those for the image's size/dimension value.
 
-- Running this tool on the same image strip multiple times for the same .imagemanifest will result in duplicate manifest entries, because the tool attempts to split the image strip into standalone images and add those to the existing manifest.
+- Running this tool on the same image strip multiple times for the same .imagemanifest will result in duplicate manifest entries. This outcome is because the tool attempts to split the image strip into standalone images and then add those to the existing manifest.
 
-- Merging (omitting /newGuids or /newIds) should only be done for tool-generated manifests. Manifests that have been customized or generated through other means might not be merged correctly.
+- Merging (omitting /newGuids or /newIds) should only be done for tool-generated manifests. Manifests that are customized or generated through other means might not be merged correctly.
 
-- Manifests that are generated for native assemblies might need to be hand-edited after generation to make the ID symbols match the resource IDs from the native assembly's .rc file.
+- Manifests generated for native assemblies might need to be hand-edited after generation to make the ID symbols match the resource IDs from the native assembly's .rc file.
 
 ## Sample Output
  **Simple image manifest**
 
- An image manifest will be similar to this .xml file:
+ An image manifest resembles this .xml file:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -85,7 +87,7 @@ The Manifest from Resources tool is a console application that takes a list of i
 
  **Image manifest for an image strip**
 
- An image manifest for an image strip will be similar to this .xml file:
+ An image manifest for an image strip is similar to this .xml file:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -122,7 +124,7 @@ The Manifest from Resources tool is a console application that takes a list of i
 
  **Image manifest for native assembly image resources**
 
- An image manifest for native images will be similar to this .xml file:
+ An image manifest for native images is similar to this .xml file:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>