Runtime: Default UTF8 Encoding constructors are inconsistent with BOM

[andschwa]

While this probably falls under "breaking change" and so will not be resolved, I'm logging this information for future confused people.

.NET Core (and .NET 4.6.1) both provide two "default constructors" for UTF8 encoding: new UTF8Encoding() and Encoding.UTF8.

The UTF8Encoding class's default constructor explicitly _does not_ use a BOM. This is documented default behavior.

The Encoding.UTF8 property (also used a default UTF-8 Encoding encoder) explicitly overrides the class's default constructor and _does_ use a BOM. This is not documented default behavior (although it may be documented elsewhere... I've only used .NET Core myself).

So one cannot simply answer "does .NET UTF-8 encoding default to using a BOM or not?" The answer is "it depends which default you asked implicitly asked for." I don't know if this was intended, but it was surely confusing.

Thanks @eerhardt for confirming with me.

[ellismg]

As you surmise, we will not be making a change here. I'm following up on getting the documentation updated so it's at least clear that the encoding from the property writes a BOM.

[andschwa]

Thanks Matt!

[GSPP]

Maybe add a new Encoding.UTF8NoBOM property?

A lot of code _requires_ not using a BOM (basically everything that does not write a whole file e.g. serialization and HTML generation). This would be useful and it would clarify that Encoding.UTF8 does emit a BOM (because why else would there be a second property that says "NoBOM").

[ellismg]

I opened this PR (https://github.com/dotnet/core-docs/pull/477) which I believe should get the docs updated.