VSIX - How to include XML documentation files in package?

Question

I've found the following article that nicely describes how PDB files of project references can be included in the VSIX package: http://www.cazzulino.com/include-pdbs-in-vsix.html.

Now I would like to do the same, but for documentation XML files that are generated by project references. I see that the XML files are already copied to the output directory of the VSIX project, but how can I make sure that they are added to the .VSIX file as well?

George Alexandria · Answer 1 · 2018-11-01T15:42:55.873

You can add anything file that you want by using VSIXSourceItem in your project file or using it from the separate imported project:

...
<!--You also can invoke this target before GetVsixSourceItems-->
<Target Name="ForceIncludeItems" AfterTargets="GetVsixSourceItems"> 
  <ItemGroup>
    <VSIXSourceItem Include="Path_to_your_xml_file" />
  </ItemGroup>
</Target>

Also you can specify wildcards and functions to select a special files which you want:

...
<VSIXSourceItem Include="*.xml" Condition="$([System.String]::new('%FileName)').StartsWith('My_start_with_pattern'))"/>

More easy but less flexible way is setting IncludeDocFilesInVSIXContainer to true:

...
<IncludeDocFilesInVSIXContainer>true</IncludeDocFilesInVSIXContainer>

In this way target will include all items which were included as @DocFileItem (as I know, by default it's only include xml file for vsix project itself).

So to add all xml files excluding suppressed by vsix build package you need to add them manually:

...
<IncludeDocFilesInVSIXContainer>true</IncludeDocFilesInVSIXContainer>

...
<Target Name="AppendNonSuppressXml" AfterTargets="GetVsixSourceItems">
    <ItemGroup>
      <SuppressXml Include="@(SuppressFromVsix->'%(FileName)')" /> <!-- store all suppressed assemblies names to avoid copying their xml files-->
    </ItemGroup>
    <PropertyGroup>
      <SuppressAsString>$([System.String]::Join(';', @(SuppressXml))</SuppressAsString> <!-- use to emulate Collections.Contains(item)-->
    </PropertyGroup>
    <ItemGroup>
      <!-- assume that xml files will be received from ReferenceCopyLocalPaths, you can use another source -->
       <VSIXSourceItem 
        Include="@(ReferenceCopyLocalPaths)"
        Condition="$(IncludeDocFilesInVSIXContainer) And '%(ReferenceCopyLocalPaths.Extension)' =='.xml' 
         And !($([System.String]::new($(SuppressAsString)).Contains('%(ReferenceCopyLocalPaths.FileName)')))" />
    </ItemGroup>
</Target>

But then we need to specify all XML files manually. Isn't there a way to include all documentation files automatically? — TWT, Oct 31 '18 at 21:36
Maybe I do something wrong, but the xml files are still not added to the VSIX after adding true to the csproj file. — TWT, Nov 01 '18 at 08:27
@TWT, Are you sure that the relevant assemblies were added to vsix by default (without a custom logic likes `VSIXSourceItem`)? What is the build package that you use to build .vsix? Would be nice if you can append project file to question. — George Alexandria, Nov 01 '18 at 09:40
They are added as project reference. I think this solution only works for documentation files generated by the VSIX itself, as described in the link in the opening post. — TWT, Nov 01 '18 at 11:50
@TWT, I append logic, that append all not suppresed xml files which were added as part of `ReferenceCopyLocalPaths`. — George Alexandria, Nov 01 '18 at 15:44

score 1 · Accepted Answer · answered Nov 05 '18 at 08:20

Answering my own question:

Apparently there is also a "DocumentationProjectOutputGroup" output group. This output group can then be added to all project references in the following way:

<PropertyGroup>
    <DefaultIncludeOutputGroupsInVSIX>
        BuiltProjectOutputGroup;
        DebugSymbolsProjectOutputGroup;
        GetCopyToOutputDirectoryItems;
        SatelliteDllsProjectOutputGroup;
        BuiltProjectOutputGroupDependencies;
        DocumentationProjectOutputGroup;
        SatelliteDllsProjectOutputGroupDependencies
    </DefaultIncludeOutputGroupsInVSIX>
</PropertyGroup>

<ItemDefinitionGroup>
    <ProjectReference>
        <IncludeOutputGroupsInVSIX>$(DefaultIncludeOutputGroupsInVSIX)</IncludeOutputGroupsInVSIX>
    </ProjectReference>
</ItemDefinitionGroup>

VSIX - How to include XML documentation files in package?

2 Answers2