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

[spboyer]

You can modify the csproj file to add the necessary files to pipeline that MSBuild needs to package up for the publish process. To add the Swagger files add the following snippet to the end of you *.csproj file before </Project>

  <Target Name="SwaggerFile">
    <ItemGroup>
      <_CustomFiles Include="bin\(Configuration)\(Platform)\*.xml" />
      <FilesForPackagingFromProject Include="%(_CustomFiles.Identity)">
        <DestinationRelativePath>%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
      </FilesForPackagingFromProject>
    </ItemGroup>
  </Target>

  <PropertyGroup>
      <CopyAllFilesToSingleFolderForPackageDependsOn>
        SwaggerFile;
        $(CopyAllFilesToSingleFolderForPackageDependsOn);
      </CopyAllFilesToSingleFolderForPackageDependsOn>
  </PropertyGroup>

This copies the documentation file to the root of the project prior to the MSBUILD process running . dotnet publish will place the file in whatever output location you specify and configuration.

cc:/ @sayedihashimi

[spboyer]

@natemcmaster (see above comment) Is this something that needs to be added to the convert doc?
http://www.natemcmaster.com/blog/2017/01/19/project-json-to-csproj/
and/or
https://github.com/mairaw/docs/blob/9aa20043b5840d98813b083dee4c26eba3451d6b/docs/core/tools/project-json-to-csproj.md

[natemcmaster]

@spboyer probably not. Those docs are focused on converting project.json to MSBuild. When I wrote the docs, I only included the breaking changes between PJ and csproj that were relevant to the format of the file. I made a followup post to address breaking changes. It might be worth added an official doc with similar content.

[eerhardt]

IMO - this highlights the main advantage of moving from project.json to MSBuild. No longer does the core build logic need to take care of every scenario. If the core build logic doesn't work for your scenario, you have the full power to make it work.

What is even better, is someone can make a "SwaggerTools" NuGet package that will inject this MSBuild logic into a project. Then all app projects need to do is add a <PackageReference> to that new package, and they get this functionality.

[natemcmaster]

this highlights the main advantage of moving from project.json to MSBuild

+1. MSBuild extensibility is awesome.

But back to the main point of this issue. Should the SDK include xml docs in the published output by default?

My vote: yes.

[sayedihashimi]

Sometimes the xml files can be large. Do we have any numbers on the size/time impact for publishing if we did this?

Update: just read through the comments, it seems like the proposal is to include the generated xml file for the project, without xml files for dependencies. That sounds like a good idea to me.

[dasMulli]

@spboyer, cc @guardrex: another workaround would be to use the $(DocumentationFile) property to emit items that are respected during publish like this:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<Target Name="IncludeDocFile" BeforeTargets="PrepareForPublish">
  <ItemGroup Condition=" '$(DocumentationFile)' != '' ">
    <_DocumentationFile Include="$(DocumentationFile)" />
    <ContentWithTargetPath Include="@(_DocumentationFile->'%(FullPath)')"
                           RelativePath="%(_DocumentationFile.Identity)"
                           TargetPath="%(_DocumentationFile.Filename)%(_DocumentationFile.Extension)"
                           CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>
</Target>

If more files are needed, more _DocumentationFile items using a pattern could be used.

[billpratt]

Is this bug actively being worked on? For now we are using csproj work arounds listed above but not ideal.

[livarcocc]

I am not sure about turning this on by default, though maybe we should have a more accessible way to have this on during publish.

[billpratt]

Having a way to enable it would be ideal considering Swashbuckle has a dependency on using this for swagger documentation.

[spboyer]

In Visual Studio, we should have the option either in the Properties of the project where you enable the xml documentation file and/or right click action to include the file in the output or publish location which then creates the entry in .csproj like @dasMulli put above.

For non-VS users, documentation noting how to do this or simplifying the entry in .csproj via a flag maybe a good/better solution.

Proposed : requires change to tooling

<PropertyGroup>
  <GenerateDocumentationFile
        CopyToPublishDirectory="PreserveNewest" 
        Option="true" />
</PropertyGroup>

cc:/ @sayedihashimi

[dasMulli]

I'd like to see a more built-in solution like building SDK support for:

<PropertyGroup>
  <PublishDocumentationFile>true</PublishDocumentationFile>
  <!-- Next one is a nice to have -->
  <PublishDependencyDocumentationFiles>true</PublishDependencyDocumentationFiles>
</PropertyGroup>

This would be easy for tooling (=> checkbox) and hand-editing csproj files. Defaults could also be set easily via the SDK, WebSDK or NuGet packages (Swashbuckle).

[ravetroll]

I found the file was being created on my desktop from VS2017 in the 'Release' Configuration but was not being created in VSTS on release configuration

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'"> <DocumentationFile>bin\Debug\netcoreapp1.1\Host.xml</DocumentationFile> </PropertyGroup>

I wondered if perhaps the 'AnyCPU' Platform was not being applied in VSTS so I removed that part from my csproj file and it built properly including my documentation file in VSTS in 'Release' so I guess AnyCPU is not the right platform setting or default platform setting in VSTS

<PropertyGroup Condition="'$(Configuration)'=='Release'"> <DocumentationFile>bin\Release\netcoreapp1.1\Host.xml</DocumentationFile> </PropertyGroup>

[pgmolloy]

I would like to vote for adding the swagger xml file to the build. My opinion is that the swagger xml file is NOT a doc file but a "necessary component" similar to a web config or an app settings file required by my Azure API to run. When deploying to Azure, my API will not start without the file. Just two cents worth :)

[dasMulli]

@pgmolloy does anything not work in your publish scenario? This has been implemented.

For those having trouble getting DocumentationFile to work, I recommend deleting it and letting MSBuild autogenerate a correct path by setting GenerateDocumentationFile instead:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

[pgmolloy]

Hi Martin, I have finally got this to work. I really don't know what fixed my issue as I decided to delete all swagger tooling and files. Redeployed the API without swagger and made sure all worked fine. I then added swagger tooling and let MSBuild do everything again and wullah all is fine. Thanks Martin for your help. Cheers Peter

[JakubNei]

None of the above worked for me, ended up including the ,xml file into project with Properties: "Build Action": Content, "Copy to Output Directory": Copy always

[peterneave]

Realised that I was calling msbuild with Release configuration (the same way the build agents were). I solved my problem by simply including the DocumentationFile in my project.

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <!-- ... -->
  <DocumentationFile>bin\Api.XML</DocumentationFile>
</PropertyGroup>

[djarvis]

None of any of the entire vastness of suggestions above worked for me. Is there some sort of updated solution that everyone else knows about except for me?

[dsplaisted]

@djarvis With the latest SDK, you should simply be able to set the GenerateDocumentationFile property to true, and the XML files will be published by default

[djarvis]

@dsplaisted Where do I set this setting? .csproj? .pubxml? Still can't get it to both generate and publish it.

[livarcocc]

It is a MSBuild property that you can set in your csproj.

<GenerateDocumentationFile>true</GenerateDocumentationFile>

[scottaddie]

@livarcocc Which version of the .NET Core SDK is required to use this MSBuild property? I'd like to get this updated in the ASP.NET Core Swashbuckle doc.

[livarcocc]

I don't remember exactly, but I always recommend installing the latest one, 2.1.300. Otherwise, 2.1.201 should also be a good one, without all the 2.1 changes.

[dasMulli]

GenerateDocumentationFile: 1.0.0
But has since had a bug for VB projects. (would output it to a wrong path)

PublishDocumentationFile, PublishReferencesDocumentationFiles: 2.0.0
These both default to true to match the behavior of project references - dotnet publish would copy the xml of <ProjectReference>es but not of the published application. Now copies all documentation by default and introduces these to properties to allow opting out of documentation publishing through these properties - #1062

2.1.300 fixed the VB issue - #1848

[louislewis2]

Hi guys,

Been working on a project where i am required to include xml documentation.
This works as expected, when adding the GenerateDocumentationFile tag.

The problem is, that I need to be able to include the xml documentation of
packages that come from nuget. I see this question was asked before, but did not see it
get addressed.

How would one go around this?

My use case is specifically for swagger / swashbuckle.
We have common projects, which have extensive documentation, we would like to have this included.

Thanks

[dsplaisted]

@louislewis2 This is being tracked in #1458. This comment specifically has links to workarounds you can apply. Thanks!

[Vaccano]

I thought I had hit this issue as well.

My issue was that I had the xml documentation file only setup to generate in Debug Build.

Make sure you don't have a condition in your .csproj file to only look at Debug Builds.

[OliverRC]

Why is this closed?

I don't get why we have to add extra Targets and hack around something that should be natively supported or at least be a configurable option.

XML Comments are no longer a development artifact with the rise of Swagger for example.
To produced self documenting swagger documentation at runtime all the XML comments must be included in the application.

What is the rationale for not copying XML documentation?
The documentation is already included in the nuget package on a build or publish?

[dsplaisted]

@OliverRC This issue is closed because we are using another issue to track it: #1458

[mtreske]

this worked for me with swagger in NetCore 3.1
`

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<PublishDocumentationFile>true</PublishDocumentationFile>
<DocumentationFile>$(MSBuildThisFileDirectory)\bin\$(Configuration)\$(TargetFramework)\AnyFile.xml</DocumentationFile>

`

[hamidpp]

you can change the existing condition:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU' OR '$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>ProjectName.xml</DocumentationFile>
  </PropertyGroup>