Documentation is outdated and too vague

[tbolon]

• This documentation uses the 1.0.0 version of the package. The current version on nuget is 2.1.
• This documentation says that you should add both PackageReference and DotNetCliToolReference. The DotNetCliToolReference does not seems to be required (as it's included in the MSBuild .props file in the package)
• The sample should use a standard library instead of an application, since the console application is not needed in this case: only serialization of type is relevant to this generator. Also the sample could use netstandard targeting instead.
• There seems to exists a lot of properties to customize the generation. This should be adressed.
• More advanced topics (using the tool directly, command-line switches) should be documented

---

Document Details

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

• ID: cb8026b7-96b0-eab2-e6ec-93d9c61e95e6
• Version Independent ID: 1ed6e1bf-7228-608d-b3fa-fa517e55386e
• Content: Microsoft XML Serializer Generator - .NET Core
• Content Source: docs/core/additional-tools/xml-serializer-generator.md
• Product: dotnet-core
• GitHub Login: @mlacouture
• Microsoft Alias: mairaw

[mairaw]

Thanks for your feedback. @mlacouture is this something you can take a look?

[tamlin-mike]

I just wanted to chime in that I have also been bitten by this outdated documentation, spending almost a complete day to get this working, only to finally find this bug issue and the only thing that helped us (remove DotNetCliToolReference, submitted in this very bugreport by @tbolon - thanks).

To be blunt: Your outdated documentation is hurting people, Microsoft. Not only that, it displays you don't have a handle on things. That is a very worrying insight that could be a conrete reason to seriously reconsider whether dependency on Microsoft software at all has become too dangerous.

[LaughingJohn]

Just to add to this, I too have been struggling to get this to work (V2.2). I get a variety of different reasons for it not producing anything. I did once manage to get it product an XML serialization assembly for a class that barely had anything in it. In my case I have a wrapper library for a WCF proxy (in .Net standard 2.0. I would have thought that WCF would be quite a common reason for using this. I really can't figure out what I need to make it generate what I want (the serializer for actual proxy added using "Add connected service)". I've currently go it complaining about System.Private.ServiceModel assembly missing and failing to find any types to serialize.

Bit confused tbh!

[ladipro]

@mairaw would it be possible to bump the priority of this issue?

• The documentation really is outdated and causing grief to the community.
• We are adding a new MSBuild error containing a link to this article so it's likely going to be read by more developers going forward (https://github.com/microsoft/msbuild/pull/5212).

[dotnet-bot]

This issue has been closed as part of the issue backlog grooming process outlined in #22351.

That automated process may have closed some issues that should be addressed. If you think this is one of them, reopen it with a comment explaining why. Tag the @dotnet/docs team for visibility.

[tbolon]

@mairaw @ladipro maybe this issue should be reopened? The example is still outdated, and now that the package and the csproj format are stable, the example could be updated and be mostly valid for future .net releases. Your thoughts?

[mairaw]

@mlacouture do you still own this?

[tdykstra]

@HongGit owns it now and will be addressing this issue.