Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

dotnet publish does not copy the documentation file with csproj #795

Closed
livarcocc opened this issue Feb 2, 2017 · 52 comments
Closed

dotnet publish does not copy the documentation file with csproj #795

livarcocc opened this issue Feb 2, 2017 · 52 comments
Labels
Bug
Milestone

Comments

@livarcocc
Copy link
Contributor

@livarcocc livarcocc commented Feb 2, 2017

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
Copy link
Member

@davkean davkean commented Feb 3, 2017

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

@masterjs
Copy link

@masterjs masterjs commented Feb 3, 2017

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
Copy link
Member

@eerhardt eerhardt commented Feb 4, 2017

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
Copy link

@masterjs masterjs commented Feb 4, 2017

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
Copy link
Contributor

@dasMulli dasMulli commented Feb 4, 2017

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.

@srivatsn srivatsn modified the milestones: 1.0 RTM, 1.1 Feb 6, 2017
@filipw
Copy link

@filipw filipw commented Feb 20, 2017

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
Copy link
Contributor

@dasMulli dasMulli commented Feb 20, 2017

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
Copy link

@spboyer spboyer commented Feb 20, 2017

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

@spboyer
Copy link

@spboyer spboyer commented Mar 3, 2017

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

@natemcmaster
Copy link
Contributor

@natemcmaster natemcmaster commented Mar 3, 2017

@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
Copy link
Member

@eerhardt eerhardt commented Mar 3, 2017

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
Copy link
Contributor

@natemcmaster natemcmaster commented Mar 3, 2017

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
Copy link
Member

@sayedihashimi sayedihashimi commented Mar 3, 2017

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
Copy link
Contributor

@dasMulli dasMulli commented Mar 14, 2017

@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
Copy link

@billpratt billpratt commented Mar 21, 2017

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

@livarcocc
Copy link
Contributor Author

@livarcocc livarcocc commented Mar 21, 2017

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
Copy link

@billpratt billpratt commented Mar 22, 2017

@spboyer
Copy link

@spboyer spboyer commented Mar 22, 2017

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
Copy link
Contributor

@dasMulli dasMulli commented Mar 22, 2017

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).

@vdevappa
Copy link

@vdevappa vdevappa commented Jun 5, 2017

For those having issues with this and service fabric, there is a slight tweak to the .csproj change you need to make to get it to work:

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

Also remember that sometimes the property group is not completely changed by Visual Studio. Ensure the below lines are present:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\Debug\net462\win7-x64\WebApiSwagger.XML</DocumentationFile> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <DocumentationFile>bin\Debug\net462\win7-x64\WebApiSwagger.XML</DocumentationFile> </PropertyGroup>
I have verified this works.

@nukec
Copy link

@nukec nukec commented Sep 13, 2017

Nothing here suggested works for me. I've tried to use @eerhardt 's answer, nothing is happening. If I click manual publish on project, xml document is added into the publish list.

I am not sure what am I doing wrong this is my .csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup Label="Globals">
    <SccProjectName>SAK</SccProjectName>
    <SccProvider>SAK</SccProvider>
    <SccAuxPath>SAK</SccAuxPath>
    <SccLocalPath>SAK</SccLocalPath>
  </PropertyGroup>

  <PropertyGroup>
    <TargetFramework>netcoreapp1.1</TargetFramework>
	<PreserveCompilationContext>true</PreserveCompilationContext>
    <PackageTargetFallback>portable-net45+win8</PackageTargetFallback>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp1.1\Api.xml</DocumentationFile>
  </PropertyGroup>
 
  
  <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <DocFile Include="bin\*\*\Api.xml" />
    </ItemGroup>

    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
  </Target>

  <ItemGroup>
    <Compile Remove="wwwroot\**" />
    <Content Remove="wwwroot\**" />
    <EmbeddedResource Remove="wwwroot\**" />
    <None Remove="wwwroot\**" />
  </ItemGroup>

  <ItemGroup>
    <None Remove="identityserver4_log.txt" />
  </ItemGroup>

  <ItemGroup>
    <Content Include="Api.xml">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="AutoMapper" Version="6.0.2" />
    <PackageReference Include="AutoMapper.Extensions.Microsoft.DependencyInjection" Version="2.0.1" />
    <PackageReference Include="Carable.Swashbuckle.AspNetCore.DocumentWithCode" Version="0.0.4" />
    <PackageReference Include="Castle.Core" Version="4.1.1" />
    <PackageReference Include="FluentValidation.AspNetCore" Version="7.0.2" />
    <PackageReference Include="IdentityServer4" Version="1.5.2" />
    <PackageReference Include="IdentityServer4.AccessTokenValidation" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
    <PackageReference Include="Microsoft.AspNetCore" Version="1.1.2" />
    <PackageReference Include="Microsoft.AspNetCore.Identity" Version="1.1.2" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="1.1.3" />
    <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="1.1.2" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="1.1.2" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="1.1.2" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="1.1.2" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer.Design" Version="1.1.2" />
	<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="1.1.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="1.1.2" />
    <PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="1.1.2" />
    <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="1.1.2" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="1.1.1" />
    <PackageReference Include="Serilog.Extensions.Logging" Version="1.4.0" />
    <PackageReference Include="Serilog.Extensions.Logging.ApplicationInsights" Version="1.1.0" />
    <PackageReference Include="StructureMap.Microsoft.DependencyInjection" Version="1.3.0" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="1.0.0" />
	<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="1.0.0" />
  </ItemGroup>
  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Views\Default\" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\Api.Business\Api.Business.csproj" />
  </ItemGroup>


</Project>
@ravetroll
Copy link

@ravetroll ravetroll commented Dec 7, 2017

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
Copy link

@pgmolloy pgmolloy commented Dec 30, 2017

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
Copy link
Contributor

@dasMulli dasMulli commented Dec 30, 2017

@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
Copy link

@pgmolloy pgmolloy commented Dec 31, 2017

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

@aeroson
Copy link

@aeroson aeroson commented Feb 14, 2018

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
Copy link

@peterneave peterneave commented Feb 14, 2018

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
Copy link

@djarvis djarvis commented Jun 19, 2018

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
Copy link
Member

@dsplaisted dsplaisted commented Jun 19, 2018

@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
Copy link

@djarvis djarvis commented Jun 20, 2018

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

@livarcocc
Copy link
Contributor Author

@livarcocc livarcocc commented Jun 20, 2018

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

<GenerateDocumentationFile>true</GenerateDocumentationFile>
@scottaddie
Copy link
Member

@scottaddie scottaddie commented Jun 22, 2018

@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
Copy link
Contributor Author

@livarcocc livarcocc commented Jun 22, 2018

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
Copy link
Contributor

@dasMulli dasMulli commented Jun 22, 2018

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
Copy link

@louislewis2 louislewis2 commented Mar 13, 2019

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
Copy link
Member

@dsplaisted dsplaisted commented Mar 13, 2019

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

@Vaccano
Copy link

@Vaccano Vaccano commented Feb 26, 2020

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
Copy link

@OliverRC OliverRC commented Mar 11, 2020

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
Copy link
Member

@dsplaisted dsplaisted commented Mar 11, 2020

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

mmitche pushed a commit to mmitche/sdk that referenced this issue Jun 5, 2020
…719.2 (dotnet#795)

- Microsoft.DotNet.Arcade.Sdk - 1.0.0-beta.19369.2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.