Merge pull request #1062 from dasMulli/feature/publish-documentation

Enable publishing XML documentation

Author: Livar

src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Publish.targets

@@ -210,6 +210,12 @@ Copyright (c) .NET Foundation. All rights reserved.
       <ResolvedFileToPublish Include="@(ResolvedAssembliesToPublish)">
         <RelativePath>%(ResolvedAssembliesToPublish.DestinationSubPath)</RelativePath>
       </ResolvedFileToPublish>
+
+      <!-- Copy the xml documentation (if enabled) -->
+      <ResolvedFileToPublish Include="@(FinalDocFile)"
+                              Condition="'$(PublishDocumentationFile)' == 'true'">
+        <RelativePath>@(FinalDocFile->'%(Filename)%(Extension)')</RelativePath>
+      </ResolvedFileToPublish>
     </ItemGroup>
 
   </Target>
@@ -220,7 +226,9 @@ Copyright (c) .NET Foundation. All rights reserved.
     <!-- TODO perform any preprocess transforms on the files -->
 
     <ItemGroup>
-      <ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)" Exclude="@(ResolvedAssembliesToPublish)">
+      <ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)"
+                                   Exclude="@(ResolvedAssembliesToPublish)"
+                                   Condition="'$(PublishReferencesDocumentationFiles)' == 'true' or '%(Extension)' != '.xml'">
         <DestinationSubPath>%(ReferenceCopyLocalPaths.DestinationSubDirectory)%(Filename)%(Extension)</DestinationSubPath>
       </ResolvedAssembliesToPublish>
     </ItemGroup>

src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Sdk.BeforeCommon.targets

@@ -137,6 +137,12 @@ Copyright (c) .NET Foundation. All rights reserved.
     <DocumentationFile />
   </PropertyGroup>
 
+  <PropertyGroup>
+    <PublishDocumentationFiles Condition="'$(PublishDocumentationFiles)' == ''">true</PublishDocumentationFiles>
+    <PublishDocumentationFile Condition="'$(PublishDocumentationFile)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishDocumentationFile>
+    <PublishReferencesDocumentationFiles Condition="'$(PublishReferencesDocumentationFiles)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishReferencesDocumentationFiles>
+  </PropertyGroup>
+
   <!-- Add a project capability so that the project properties in the IDE can show the option to generate an XML documentation file without specifying the filename -->
   <ItemGroup>
     <ProjectCapability Include="GenerateDocumentationFile" />

test/Microsoft.NET.Publish.Tests/GivenThatWeWantToPublishAProjectWithDependencies.cs

@@ -13,6 +13,8 @@
 using System.Runtime.InteropServices;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
+using System.Collections.Generic;
+using Microsoft.NET.TestFramework.ProjectConstruction;
 
 namespace Microsoft.NET.Publish.Tests
 {
@@ -189,6 +191,98 @@ public void It_publishes_projects_with_filter_and_rid()
 
 //TODO: Enable testing the run once dotnet host has the notion of looking up shared packages
         }
+
+
+        [Theory]
+        [InlineData("GenerateDocumentationFile=true", true, true)]
+        [InlineData("GenerateDocumentationFile=true;PublishDocumentationFile=false", false, true)]
+        [InlineData("GenerateDocumentationFile=true;PublishReferencesDocumentationFiles=false", true, false)]
+        [InlineData("GenerateDocumentationFile=true;PublishDocumentationFiles=false", false, false)]
+        public void It_publishes_documentation_files(string properties, bool expectAppDocPublished, bool expectLibProjectDocPublished)
+        {
+            var kitchenSinkAsset = _testAssetsManager
+                .CopyTestAsset("KitchenSink", identifier: $"{expectAppDocPublished}_{expectLibProjectDocPublished}")
+                .WithSource();
+            kitchenSinkAsset.Restore("TestApp");
+            
+            var publishCommand = new PublishCommand(Stage0MSBuild, Path.Combine(kitchenSinkAsset.TestRoot, "TestApp"));
+            var publishResult = publishCommand.Execute("/p:" + properties);
+
+            publishResult.Should().Pass();
+
+            var publishDirectory = publishCommand.GetOutputDirectory();
+
+            if (expectAppDocPublished)
+            {
+                publishDirectory.Should().HaveFile("TestApp.xml");
+            }
+            else
+            {
+                publishDirectory.Should().NotHaveFile("TestApp.xml");
+            }
+
+            if (expectLibProjectDocPublished)
+            {
+                publishDirectory.Should().HaveFile("TestLibrary.xml");
+            }
+            else
+            {
+                publishDirectory.Should().NotHaveFile("TestLibrary.xml");
+            }
+        }
+
+        [Theory]
+        [InlineData("PublishReferencesDocumentationFiles=false", false)]
+        [InlineData("PublishReferencesDocumentationFiles=true", true)]
+        public void It_publishes_referenced_assembly_documentation(string property, bool expectAssemblyDocumentationFilePublished)
+        {
+            var identifier = property.Replace("=", "");
+
+            var libProject = new TestProject
+            {
+                Name = "NetStdLib",
+                IsSdkProject = true,
+                TargetFrameworks = "netstandard1.0"
+            };
+
+            var libAsset = _testAssetsManager.CreateTestProject(libProject, identifier: identifier)
+                .Restore("NetStdLib");
+
+            var libPublishCommand = new PublishCommand(Stage0MSBuild, Path.Combine(libAsset.TestRoot, "NetStdLib"));
+            var libPublishResult = libPublishCommand.Execute("/t:Publish", "/p:GenerateDocumentationFile=true");
+            libPublishResult.Should().Pass();
+            var publishedLibPath = Path.Combine(libPublishCommand.GetOutputDirectory("netstandard1.0").FullName, "NetStdLib.dll");
+
+            var appProject = new TestProject
+            {
+                Name = "TestApp",
+                IsSdkProject = true,
+                IsExe = true,
+                TargetFrameworks = "netcoreapp2.0",
+                RuntimeFrameworkVersion = RepoInfo.NetCoreApp20Version,
+                References = { publishedLibPath }
+            };
+
+            var appAsset = _testAssetsManager.CreateTestProject(appProject, identifier: identifier);
+            var appSourcePath  = Path.Combine(appAsset.TestRoot, "TestApp");
+
+            new RestoreCommand(Stage0MSBuild, appSourcePath).Execute().Should().Pass();
+            var appPublishCommand = new PublishCommand(Stage0MSBuild, appSourcePath);
+            var appPublishResult = appPublishCommand.Execute("/p:" + property);
+            appPublishResult.Should().Pass();
+
+            var appPublishDirectory = appPublishCommand.GetOutputDirectory("netcoreapp2.0");
+
+            if (expectAssemblyDocumentationFilePublished)
+            {
+                appPublishDirectory.Should().HaveFile("NetStdLib.xml");
+            }
+            else
+            {
+                appPublishDirectory.Should().NotHaveFile("NetStdLib.xml");
+            }
+        }
+
         private static JObject ReadJson(string path)
         {
             using (JsonTextReader jsonReader = new JsonTextReader(File.OpenText(path)))