XML Documentation file is not included in publish folder - asp.net-core

Question

I've selected "Xml documentation file" in my ASP.NET Core MVC application and it displays "bin\Debug\net452\MyProject.xml" as output folder. The problem is that this file doesn't exist in publish folder. Do I need to someting additional to include it? Using .NET Core 1.0-RC4 and VS.NET 2017 RC4 (new csproject format).

Answer 1

If you're using project.json then you can control the files and folders that are both included and excluded by the publish process:
"publishOptions": {
"include": [
"wwwroot",
"appsettings.json",
"appsettings.*.json",
"web.config"
],
"exclude": [
"wwwroot/less"
]
}
For .csproj based projects here is a good resource for replicating old project.json settings in XML, for example:
<ItemGroup>
<Compile Include="..\Shared\*.cs" Exclude="..\Shared\Not\*.cs" />
<EmbeddedResource Include="..\Shared\*.resx" />
<Content Include="Views\**\*" PackagePath="%(Identity)" />
<None Include="some/path/in/project.txt" Pack="true" PackagePath="in/package.txt" />
<None Include="notes.txt" CopyToOutputDirectory="Always" />
<!-- CopyToOutputDirectory = { Always, PreserveNewest, Never } -->
<Content Include="files\**\*" CopyToPublishDirectory="PreserveNewest" />
<None Include="publishnotes.txt" CopyToPublishDirectory="Always" />
<!-- CopyToPublishDirectory = { Always, PreserveNewest, Never } -->
</ItemGroup>

Answer 2

Apparently this is not implemented in with dotnet publish but will be in the near future: https://github.com/dotnet/sdk/issues/795

Answer 3

The project.json file should have the "xmlDoc": true under "buildOptions":
{
"buildOptions": {
"xmlDoc": true
}
}
If you have documentation in your code like this:
/// <summary>
/// Documentation for FooClass
/// </summary>
public static class FooClass
{
// ...
}
Then you should have an xml file in your output that looks like this:
<doc>
<assembly>
<name>Foo.Bar</name>
</assembly>
<members>
<member name="T:Foo.Bar.FooClass">
<summary>
Documentation for FooClass
</summary>
</member>
</members>
</doc>

Answer 4

Tested on 1.1.2
ResolvedFileToPublish is the Item that publish uses to know which files to put in the publish folder. The Include is the file's source, and the RelativePath is where inside the publish folder the file should be placed.
ComputeFilesToPublish is exactly as its name implies - it is the Target that gathers all the files to be published.
<Target Name="CopyDocumentationFile"
AfterTargets="ComputeFilesToPublish">
<ItemGroup>
<ResolvedFileToPublish Include="#(FinalDocFile)"
RelativePath="#(FinalDocFile->'%(Filename)%(Extension)')" />
</ItemGroup>
</Target>
Just add this target to your .csproj and make sure that
GenerateDocumentationFile is set to true
<GenerateDocumentationFile>true</GenerateDocumentationFile>
https://github.com/dotnet/sdk/issues/795#issuecomment-289782712

Answer 5

In Asp.net Core, if you are having trouble setting DocumentationFile to work, we can do that by setting GenerateDocumentationFile property in .csproj:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>