PublishTrimmed cause XML documentation to disappear

[Jérémy VIGNELLES]

In .NET core >= 3.0, when <PublishTrimmed>true</PublishTrimmed> and the project that uses this package is published, the following libraries get trimmed, because reflection is used:

• System.IO.FileSystem
• System.Xml.XPath.XDocument
• System.Xml.Linq

Impact

XML documentation cannot be loaded by this library. This can affect NSwag, where the generated swagger.json lacks documentation for published applications with this flag enabled. This is not blocking as the application works normally, but it's a difference between the application tested in the dev environment and the application that gets pushed into production.

Workaround

You can use one of the technique described here.
For example, you could add these lines into your .csproj:

  <ItemGroup>
    <TrimmerRootAssembly Include="System.IO.FileSystem" />
    <TrimmerRootAssembly Include="System.Xml.XPath.XDocument" />
    <TrimmerRootAssembly Include="System.Xml.Linq" />
  </ItemGroup>

What are the options for Namotion.Reflection / NSwag

• Do nothing : People that gets those issues will be redirected here after a quick google search
• Warn users clearly in the documentation : "This package makes use of reflection, if you are using PublishTrimmed in your project, please see ..."
• Explicitely force users to include the TrimmerRootAssembly by adding a build/<PackageName>.props into Namotion.Reflection's package, which contains the above XML inside a <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> tag.
  In N.R.csproj, add this so that it gets packed:

  <ItemGroup>
    <None Include="build\Namotion.Reflection.props" Pack="True" PackagePath="build\" />
  </ItemGroup>

Direct references to this package would then have the TrimmerRootAssembly added, and these assemblies should not get trimmed.

For indirect references (like in NJS.csproj), you can use:

<PackageReference Include="Namotion.Reflection" Version="XXX" PrivateAssets="None" />

The value of None might be overkill here, see the doc. The idea is to tell msbuild "Let properties/item groups leak into my project, and get referenced as well when someone references me"

• Remove the use of Dynamically loaded APIs. You can do that by keeping the code between

#if NETSTANDARD1_0
// Dynamically loaded API
#else
// API is always present, and use it directly
#endif

Impacted target frameworks

Netstandard & netcoreapp that get included in a netcoreapp application.