Expand project description and readme with XML usage

devlooped · Sep 30, 2024 · f39f692 · f39f692
1 parent 66f2cdf
commit f39f692
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 24 deletions.
diff --git a/src/ThisAssembly.Vsix/ThisAssembly.Vsix.csproj b/src/ThisAssembly.Vsix/ThisAssembly.Vsix.csproj
@@ -10,8 +10,8 @@
 
   <PropertyGroup>
     <PackageId>ThisAssembly.Vsix</PackageId>
-    <Description>This package generates a static `ThisAssembly.Vsix` class with public 
-constants exposing key VSIX manifest properties. For example:
+    <Description>Allows consuming VSIX manifest properties from code, as well as 
+MSBuild project properties from the VSIX manifest. For example:
 
   partial class ThisAssembly
   {
@@ -20,6 +20,17 @@ constants exposing key VSIX manifest properties. For example:
           public const string Id = "MyVsix";
       }
   }
+
+or 
+
+  &lt;PackageManifest Version=&quot;2.0.0&quot; ...&gt;
+    &lt;Metadata&gt;
+      &lt;Identity Id=&quot;|%CurrentProject%;VsixId|&quot; Version=&quot;|%CurrentProject%;VsixVersion|&quot; Language=&quot;|%CurrentProject%;VsixLanguage|&quot; Publisher=&quot;|%CurrentProject%;VsixPublisher|&quot; /&gt;
+      &lt;DisplayName&gt;|%CurrentProject%;VsixDisplayName|&lt;/DisplayName&gt;
+      &lt;Description&gt;|%CurrentProject%;VsixDescription|&lt;/Description&gt;
+    &lt;/Metadata&gt;
+    ...
+  &lt;/PackageManifest&gt;
 </Description>
   </PropertyGroup>
 

diff --git a/src/ThisAssembly.Vsix/readme.md b/src/ThisAssembly.Vsix/readme.md
@@ -1,29 +1,11 @@
 <!-- include https://github.com/devlooped/.github/raw/main/sponsorlinkr.md -->
 <!-- #vsix -->
-This package generates a static `ThisAssembly.Vsix` class with public 
-constants exposing key VSIX manifest properties.
+Allows consuming VSIX manifest properties from code, as well as 
+MSBuild project properties from the VSIX manifest. For example:
 
 ![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Vsix.png)
 
-For example:
-
-```csharp
-  partial class ThisAssembly
-  {
-      public static partial class Vsix
-      {
-          public const string Id = "MyVsix";
-      }
-  }
-```
-
-In addition to making the [VSIX manifest metadata](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element) 
-properties available as constants, the package also provides targets for those properties 
-with sensible defaults from project properties so that the manifest can leverage 
-[placeolder syntax](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element) 
-and avoid duplication. 
-
-For example, the following `source.extension.vsixmanifest` uses values from MSBuild exclusively:
+And in the `source.extension.vsixmanifest`:
 ```xml
 <PackageManifest Version="2.0.0" 
                  xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" 
@@ -38,6 +20,12 @@ For example, the following `source.extension.vsixmanifest` uses values from MSBu
 </PackageManifest>
 ```
 
+As shown above, in addition to making the [VSIX manifest metadata](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element) 
+properties available as constants, the package also provides targets for those properties 
+with sensible defaults from project properties so that the manifest can leverage 
+[placeolder syntax](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element) 
+and avoid duplication. 
+
 The available properties and their default values are:
 
 | Name              | Default Value                       |
@@ -51,7 +39,7 @@ The available properties and their default values are:
 | VsixLanguage      | `$(NeutralLanguage)` or 'en-US'     |
 | VsixDescription   | `$(Description)`                    |
 
-As shown in the example above, the syntax for using these properties from the `.vsxmanifest` is 
+As shown in the example above, the syntax for using these properties from the `source.extension.vsixmanifest` is 
 `|%CurrentProject%;[PROPERTY]|`. This is because the package defines a corresponding target to 
 retrieve each of the above properties. You can provide a different value for each property via 
 MSBuild as usual, of course.