dotnet publish does not copy the documentation file with csproj

[livarcocc]

Steps to reproduce

Have a solution with multiple projects
The main "web" project has the GenerateDocumentationFile set to true

Expected behavior

When I run dotnet publish of the main "web" project, I expect that the XML documentation file is copied into the publishing folder. (Note the build will generate the file as it should.)

Actual behavior

When I run dotnet publish of the main "web" project, it does not copy the XML documentation file to the psublish folder.

My workaround

My current workaround is to update the csproj of the main web project and manually copy the file:

<Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
		<ItemGroup>
			<DocFile Include="bin\**\**\PROJECT_XYZ.xml" />
		</ItemGroup>
		<Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false"  />
  </Target>

Environment data

.NET Command Line Tools (1.0.0-rc3-004530)

Product Information:
Version: 1.0.0-rc3-004530
Commit SHA-1 hash: 0de3338

Runtime Environment:
OS Name: Windows
OS Version: 6.3.9600
OS Platform: Windows
RID: win81-x64
Base Path: C:\Program Files\dotnet\sdk\1.0.0-rc3-004530

This issue has been copied over from https://github.com/dotnet/cli/issues/5562.

[davkean]

@masterjs What's the expectation around this? Why do you expect the XML file to be published - it's a dev artefact.

[masterjs]

Hello @davkean ,
My project is a big WebAPI netcore and like many API, I'm using Swagger whom needs the XML documentation file if I want to have a good documentation for my API. Also, it use to work when I was using .xproj.

Also, another of my project (solution with multiple projects) has the flag GenerateDocumentationFile turned On and somehow that one is copied over.

So in a nutshell, it use to work and now I see two different things contradicting themselves.

thank you,
JS

[eerhardt]

Do you also expect that P2P references' doc files are published? What about doc files from NuGet packages?

I think since documentation files aren't typically used at runtime, they shouldn't be published by default.

Projects that need this behavior can add their own target that runs during publish and adds the documentation file to the @(ResolvedFileToPublish) item, which will copy the xml file to the publish directory. It isn't necessarily behavior that the core SDK has to provide.

[masterjs]

For my case, since It's for a web api I only care about the generated documentation. I dont mind and understand if it needs a little bit more work like I did for my work-around. The main problem was that it was a different behavior from xproj when I migrated to csproj and the documentation file of other projects was still copied.

[dasMulli]

Documentation files are what Swashbuckle can use at runtime to enrich the generated Swagger API description. It's nice for Web API projects because you just need to write a documentation once that works for IntelliSense, doc generation tools AND runtime Swagger generation, making it more than just a dev artifact. So it does make sense to publish it with the application in some scenarios.

[filipw]

I agree, it's necessary for situations like auto-generated Swagger.
It also worked for project.json so it's really a breaking change for folks migrating to csproj

[dasMulli]

using xml comments for swagger is already documented on docs.microsoft.com by @spboyer so maybe the doc would need to be updated that this won't work with the 1.0 tooling when published?

[spboyer]

The swagger doc has been updated in the csproj branch, will be pushing that to live when RTM is released approx Mar 7