XML Comments section is not working as described for ASP.NET Core 1.1

[Structed]

First, the code to enable the loading of the XML file in the Startup.cs is incorrect for ASP.NET Core 1.1. The Correct lines are as follows:

var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
setupAction.IncludeXmlComments(xmlPath);

Second, this will not work at all if the app was published. For this, you have to add a Target to the csproj file. See example by @spboyer here: https://github.com/spboyer/copydocfile-example

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 14fce65f-1337-58cb-2193-8d8e0e62792d
• Version Independent ID: 59222460-a971-e76e-4fe9-23d4d7d768ee
• Content: Get started with Swashbuckle and ASP.NET Core
• Content Source: aspnetcore/tutorials/getting-started-with-swashbuckle.md
• Service: unspecified
• Product: asp.net-core
• GitHub Login: @zuckerthoben
• Microsoft Alias: scaddie

[scottaddie]

@Structed Thank you for pointing this out. You're correct that the GetExecutingAssembly method isn't available until 2.0. I'm working on this now.

[Structed]

Thanks, @scottaddie! Please also have a look at the second thing. Since you're describing the use of XML Comments, you should go all the way including that "hack" to add a copy target to the csproj file. I also think, this is still required in ASP.NET Core 2.0?

[scottaddie]

@Structed I plan to address your point about app publishing in the next week or so. This issue won't be closed until that's completed.

[scottaddie]

@rynowak Please review Shayne's blog post (linked above). Would you like this publish detail included in the doc?

[rynowak]

/cc @vijayrkn - this is publish related - who should review?

[vijayrkn]

@dsplaisted

[dsplaisted]

@vijayrkn What am I supposed to review here?

[vijayrkn]

https://github.com/spboyer/copydocfile-example

Is this the right extensibility for publish?

[dsplaisted]

The solution in the blog post is no longer needed with newer SDKs. Rather than working around the issue when using an old SDK, I would recommend that people use the latest SDK (they can still target .NET Core 1.x with it).

If we were going to put a workaround in the docs, I would suggest the one here: dotnet/sdk#795 (comment)

[scottaddie]

@dsplaisted Was this issue fixed in 2.1.300? I'd like to identify the SDK version that's needed.

[dsplaisted]

@scottaddie According to @dasMulli, it was fixed in 2.0.0, and there was a VB-specific issue with it that was fixed in 2.1.300.

[dasMulli]

You can slim the csproj sample down to

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Reasons:

1. Property group in the sample is conditioned to debug mode. you don't want that to also support publishing the documentation in release builds.
2. GenerateDocumentationFile is much nicer. Also, the original sample should have used $(AssemblyName) instead of $(MSBuildProjectName) for correctness.
3. Only append to NoWarn instead of fully redefining it. This allows to also consume changes such as Removing 1705 from the NoWarn list for CSharp. sdk#1868 where the default NoWarn for c# was changed.