UTF8Encoding Constructor (Boolean, Boolean)


Initializes a new instance of the UTF8Encoding class. Parameters specify whether to provide a Unicode byte order mark and whether to throw an exception when an invalid encoding is detected.

Namespace:   System.Text
Assembly:  mscorlib (in mscorlib.dll)

	bool encoderShouldEmitUTF8Identifier,
	bool throwOnInvalidBytes


Type: System::Boolean

true to specify that the GetPreamble method should return a Unicode byte order mark; otherwise, false. See the Remarks section for more information.

Type: System::Boolean

true to throw an exception when an invalid encoding is detected; otherwise, false.

The encoderShouldEmitUTF8Identifier parameter controls the operation of the GetPreamble method. If true, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If false, it returns a zero-length byte array. However, setting encoderShouldEmitUTF8Identifier to true does not cause the GetBytes method to prefix the BOM at the beginning of the byte array, nor does it cause the GetByteCount method to include the number of bytes in the BOM in the byte count.

If throwOnInvalidBytes is true, a method that detects an invalid byte sequence throws an System::ArgumentException exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored.


For security reasons, you should enable error detection by calling a constructor that includes a throwOnInvalidBytes parameter and setting that parameter to true.

The following example creates a new UTF8Encoding instance, specifying that the GetPreamble method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. The behavior of this constructor is compared to the default UTF8Encoding() constructor, which does not throw an exception when an invalid encoding is detected. The two UTF8Encoding instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low surrogate.

using namespace System;
using namespace System::Text;

void ShowArray(Array^ theArray)
   for each (Byte b in theArray) {
      Console::Write( "{0:X2} ", b);

int main()
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   UTF8Encoding^ utf8ThrowException = gcnew UTF8Encoding(false,true);

   // This array contains two high surrogates in a row (\uD801, \uD802).
   array<Char>^chars = {'a','b','c',L'\xD801',L'\xD802','d'};

   // The following method call will not throw an exception.
   array<Byte>^bytes = utf8->GetBytes( chars );
   ShowArray( bytes );

   try {

      // The following method call will throw an exception.
      bytes = utf8ThrowException->GetBytes( chars );
   catch (EncoderFallbackException^ e ) {
            Console::WriteLine("{0} exception\nMessage:\n{1}",
                               e->GetType()->Name, e->Message);


Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top