Restructure XmlDocGenerator as MSBuild SDK package for NuGet distribution

Co-authored-by: omegaleo <5655201+omegaleo@users.noreply.github.com>

OmegaLeo.HelperLib.Changelog/OmegaLeo.HelperLib.Changelog.csproj

@@ -38,20 +38,7 @@
       <ProjectReference Include="..\OmegaLeo.HelperLib.Shared\OmegaLeo.HelperLib.Shared.csproj" />
     </ItemGroup>
 
-    <!-- Post-build target to generate XML documentation from DocumentationAttribute -->
-    <Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
-        <PropertyGroup>
-            <XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
-            <TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
-            <TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
-        </PropertyGroup>
-        
-        <Message Text="[DocumentationAttribute] Augmenting XML documentation for $(TargetName) from DocumentationAttribute" Importance="high" Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')" />
-        
-        <Exec Command="dotnet &quot;$(XmlDocGenExe)&quot; &quot;$(TargetAssembly)&quot; &quot;$(TargetXmlDoc)&quot;"
-              Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
-              IgnoreExitCode="true"
-              ContinueOnError="true" />
-    </Target>
+    <!-- Import local XML doc generation for development -->
+    <Import Project="../XmlDocGeneratorLocal.props" Condition="Exists('../XmlDocGeneratorLocal.props')" />
 
 </Project>

OmegaLeo.HelperLib.Documentation/OmegaLeo.HelperLib.Documentation.csproj

@@ -36,20 +36,7 @@
       </None>
     </ItemGroup>
 
-    <!-- Post-build target to generate XML documentation from DocumentationAttribute -->
-    <Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
-        <PropertyGroup>
-            <XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
-            <TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
-            <TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
-        </PropertyGroup>
-        
-        <Message Text="[DocumentationAttribute] Augmenting XML documentation for $(TargetName) from DocumentationAttribute" Importance="high" Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')" />
-        
-        <Exec Command="dotnet &quot;$(XmlDocGenExe)&quot; &quot;$(TargetAssembly)&quot; &quot;$(TargetXmlDoc)&quot;"
-              Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
-              IgnoreExitCode="true"
-              ContinueOnError="true" />
-    </Target>
+    <!-- Import local XML doc generation for development -->
+    <Import Project="../XmlDocGeneratorLocal.props" Condition="Exists('../XmlDocGeneratorLocal.props')" />
 
 </Project>

OmegaLeo.HelperLib.Game/OmegaLeo.HelperLib.Game.csproj

@@ -31,20 +31,7 @@
       </None>
     </ItemGroup>
 
-    <!-- Post-build target to generate XML documentation from DocumentationAttribute -->
-    <Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
-        <PropertyGroup>
-            <XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
-            <TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
-            <TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
-        </PropertyGroup>
-        
-        <Message Text="[DocumentationAttribute] Augmenting XML documentation for $(TargetName) from DocumentationAttribute" Importance="high" Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')" />
-        
-        <Exec Command="dotnet &quot;$(XmlDocGenExe)&quot; &quot;$(TargetAssembly)&quot; &quot;$(TargetXmlDoc)&quot;"
-              Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
-              IgnoreExitCode="true"
-              ContinueOnError="true" />
-    </Target>
+    <!-- Import local XML doc generation for development -->
+    <Import Project="../XmlDocGeneratorLocal.props" Condition="Exists('../XmlDocGeneratorLocal.props')" />
 
 </Project>

OmegaLeo.HelperLib.Shared/OmegaLeo.HelperLib.Shared.csproj

@@ -31,19 +31,7 @@
         </None>
     </ItemGroup>
 
-    <!-- Post-build target to generate XML documentation from DocumentationAttribute -->
-    <Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
-        <PropertyGroup>
-            <XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
-            <TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
-            <TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
-        </PropertyGroup>
-        
-        <Message Text="[DocumentationAttribute] Augmenting XML documentation for $(TargetName) from DocumentationAttribute" Importance="high" Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')" />
-        
-        <Exec Command="dotnet &quot;$(XmlDocGenExe)&quot; &quot;$(TargetAssembly)&quot; &quot;$(TargetXmlDoc)&quot;"
-              Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
-              IgnoreExitCode="true"
-              ContinueOnError="true" />
-    </Target>
+    <!-- Import local XML doc generation for development -->
+    <Import Project="../XmlDocGeneratorLocal.props" Condition="Exists('../XmlDocGeneratorLocal.props')" />
+
 </Project>

OmegaLeo.HelperLib.XmlDocGenerator/OmegaLeo.HelperLib.XmlDocGenerator.csproj

@@ -5,13 +5,41 @@
     <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <PackAsTool>true</PackAsTool>
-    <ToolCommandName>xmldocgen</ToolCommandName>
+    <PackAsTool>false</PackAsTool>
     <PackageId>OmegaLeo.HelperLib.XmlDocGenerator</PackageId>
+    <Version>1.0.0</Version>
+    <Authors>Nuno "Omega Leo" Diogo</Authors>
+    <Description>MSBuild task to generate XML documentation from DocumentationAttribute</Description>
+    <PackageProjectUrl>https://github.com/omegaleo/HelperLib</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/omegaleo/HelperLib</RepositoryUrl>
+    <PackageLicenseExpression>AGPL-3.0-only</PackageLicenseExpression>
+    <PackageTags>msbuild;xml;documentation;attributes</PackageTags>
+    
+    <!-- MSBuild Package Settings -->
+    <DevelopmentDependency>true</DevelopmentDependency>
+    <IncludeBuildOutput>false</IncludeBuildOutput>
+    <NoWarn>NU5100</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="System.Reflection.Metadata" Version="8.0.0" />
+    <PackageReference Include="System.Reflection.Metadata" Version="8.0.0" PrivateAssets="all" />
+  </ItemGroup>
+
+  <!-- Include the tool exe and its dependencies in the package -->
+  <Target Name="AddToolToPackage" BeforeTargets="_GetPackageFiles">
+    <ItemGroup>
+      <None Include="$(OutputPath)**\*.dll" Pack="true" PackagePath="tools/net8.0/" />
+      <None Include="$(OutputPath)$(AssemblyName).runtimeconfig.json" Pack="true" PackagePath="tools/net8.0/" />
+      <None Include="$(OutputPath)$(AssemblyName).deps.json" Pack="true" PackagePath="tools/net8.0/" />
+    </ItemGroup>
+  </Target>
+
+  <!-- Include build targets in the package -->
+  <ItemGroup>
+    <None Include="build\OmegaLeo.HelperLib.XmlDocGenerator.props" Pack="true" PackagePath="build\" />
+    <None Include="build\OmegaLeo.HelperLib.XmlDocGenerator.targets" Pack="true" PackagePath="build\" />
+    <None Include="buildMultiTargeting\OmegaLeo.HelperLib.XmlDocGenerator.props" Pack="true" PackagePath="buildMultiTargeting\" />
+    <None Include="buildMultiTargeting\OmegaLeo.HelperLib.XmlDocGenerator.targets" Pack="true" PackagePath="buildMultiTargeting\" />
   </ItemGroup>
 
 </Project>

OmegaLeo.HelperLib.XmlDocGenerator/build/OmegaLeo.HelperLib.XmlDocGenerator.props

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <!-- Enable XML documentation generation from DocumentationAttribute by default -->
+    <GenerateXmlDocFromDocumentationAttribute Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == ''">true</GenerateXmlDocFromDocumentationAttribute>
+  </PropertyGroup>
+</Project>

OmegaLeo.HelperLib.XmlDocGenerator/build/OmegaLeo.HelperLib.XmlDocGenerator.targets

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+  <Target Name="GenerateXmlDocFromDocumentationAttribute" 
+          AfterTargets="CoreCompile" 
+          Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == 'true' And '$(TargetFramework)' != ''">
+    
+    <PropertyGroup>
+      <!-- Path to the XmlDocGenerator tool in the NuGet package -->
+      <XmlDocGenToolPath>$(MSBuildThisFileDirectory)..\tools\net8.0\OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenToolPath>
+      <TargetAssemblyPath>$(IntermediateOutputPath)$(TargetFileName)</TargetAssemblyPath>
+      <TargetXmlDocPath>$(IntermediateOutputPath)$(TargetName).xml</TargetXmlDocPath>
+    </PropertyGroup>
+
+    <Message Text="[DocumentationAttribute] Generating XML documentation from DocumentationAttribute for $(TargetName)" 
+             Importance="high" 
+             Condition="Exists('$(XmlDocGenToolPath)') And Exists('$(TargetAssemblyPath)')" />
+    
+    <Message Text="[DocumentationAttribute] Tool not found at: $(XmlDocGenToolPath)" 
+             Importance="high" 
+             Condition="!Exists('$(XmlDocGenToolPath)')" />
+    
+    <!-- Run the XmlDocGenerator tool -->
+    <Exec Command="dotnet &quot;$(XmlDocGenToolPath)&quot; &quot;$(TargetAssemblyPath)&quot; &quot;$(TargetXmlDocPath)&quot;"
+          Condition="Exists('$(XmlDocGenToolPath)') And Exists('$(TargetAssemblyPath)')"
+          IgnoreExitCode="true"
+          ContinueOnError="true" />
+  </Target>
+
+</Project>

OmegaLeo.HelperLib.XmlDocGenerator/buildMultiTargeting/OmegaLeo.HelperLib.XmlDocGenerator.props

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="..\build\OmegaLeo.HelperLib.XmlDocGenerator.props" />
+</Project>

OmegaLeo.HelperLib.XmlDocGenerator/buildMultiTargeting/OmegaLeo.HelperLib.XmlDocGenerator.targets

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="..\build\OmegaLeo.HelperLib.XmlDocGenerator.targets" />
+</Project>

OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj

@@ -33,22 +33,7 @@
       <ProjectReference Include="..\OmegaLeo.HelperLib.Shared\OmegaLeo.HelperLib.Shared.csproj" />
     </ItemGroup>
 
-    <!-- Post-build target to generate XML documentation from DocumentationAttribute -->
-    <Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
-        <PropertyGroup>
-            <XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
-            <TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
-            <TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
-        </PropertyGroup>
-        
-        <Message Text="[DocumentationAttribute] Augmenting XML documentation for $(TargetName) from DocumentationAttribute" Importance="high" Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')" />
-        <Message Text="[DocumentationAttribute] XmlDocGen tool not found at: $(XmlDocGenExe)" Importance="high" Condition="!Exists('$(XmlDocGenExe)')" />
-        <Message Text="[DocumentationAttribute] Target assembly not found at: $(TargetAssembly)" Importance="high" Condition="!Exists('$(TargetAssembly)')" />
-        
-        <Exec Command="dotnet &quot;$(XmlDocGenExe)&quot; &quot;$(TargetAssembly)&quot; &quot;$(TargetXmlDoc)&quot;"
-              Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
-              IgnoreExitCode="true"
-              ContinueOnError="true" />
-    </Target>
+    <!-- Import local XML doc generation for development -->
+    <Import Project="../XmlDocGeneratorLocal.props" Condition="Exists('../XmlDocGeneratorLocal.props')" />
 
 </Project>

XmlDocGeneratorLocal.props

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+  This file provides local development support for XML documentation generation.
+  Import this file in projects that use DocumentationAttribute during development.
+  For NuGet consumers, the XmlDocGenerator package will provide this automatically.
+-->
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+  <PropertyGroup>
+    <!-- Enable XML documentation generation from DocumentationAttribute by default -->
+    <GenerateXmlDocFromDocumentationAttribute Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == ''">true</GenerateXmlDocFromDocumentationAttribute>
+  </PropertyGroup>
+
+  <Target Name="GenerateXmlDocFromDocumentationAttribute_Local" 
+          AfterTargets="CoreCompile" 
+          Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == 'true' And '$(TargetFramework)' != ''">
+    
+    <PropertyGroup>
+      <!-- For local development, use the built tool from the sibling project -->
+      <XmlDocGenToolPath_Local>$(MSBuildThisFileDirectory)OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenToolPath_Local>
+      <TargetAssemblyPath>$(IntermediateOutputPath)$(TargetFileName)</TargetAssemblyPath>
+      <TargetXmlDocPath>$(IntermediateOutputPath)$(TargetName).xml</TargetXmlDocPath>
+    </PropertyGroup>
+
+    <Message Text="[DocumentationAttribute] Generating XML documentation from DocumentationAttribute for $(TargetName)" 
+             Importance="high" 
+             Condition="Exists('$(XmlDocGenToolPath_Local)') And Exists('$(TargetAssemblyPath)')" />
+    
+    <Message Text="[DocumentationAttribute] Local tool not found at: $(XmlDocGenToolPath_Local)" 
+             Importance="high" 
+             Condition="!Exists('$(XmlDocGenToolPath_Local)')" />
+    
+    <!-- Run the XmlDocGenerator tool -->
+    <Exec Command="dotnet &quot;$(XmlDocGenToolPath_Local)&quot; &quot;$(TargetAssemblyPath)&quot; &quot;$(TargetXmlDocPath)&quot;"
+          Condition="Exists('$(XmlDocGenToolPath_Local)') And Exists('$(TargetAssemblyPath)')"
+          IgnoreExitCode="true"
+          ContinueOnError="true" />
+  </Target>
+
+</Project>