UTF8Encoding Constructors

Definition

Initializes a new instance of the UTF8Encoding class.

Overloads

UTF8Encoding()

Initializes a new instance of the UTF8Encoding class.

UTF8Encoding(Boolean)

Initializes a new instance of the UTF8Encoding class. A parameter specifies whether to provide a Unicode byte order mark.

UTF8Encoding(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.

UTF8Encoding()

Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs

Initializes a new instance of the UTF8Encoding class.

public UTF8Encoding ();

Examples

The following example creates a new UTF8Encoding instance and displays its name.

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        UTF8Encoding utf8 = new UTF8Encoding();
        String encodingName = utf8.EncodingName;
        Console.WriteLine("Encoding name: " + encodingName);
    }
}

Remarks

This constructor creates an instance that does not provide a Unicode byte order mark and does not throw an exception when an invalid encoding is detected.

Caution

For security reasons, we recommend that you enable error detection by calling a constructor with a throwOnInvalidBytes parameter and setting its value to true.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

UTF8Encoding(Boolean)

Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs

Initializes a new instance of the UTF8Encoding class. A parameter specifies whether to provide a Unicode byte order mark.

public UTF8Encoding (bool encoderShouldEmitUTF8Identifier);

Parameters

encoderShouldEmitUTF8Identifier
Boolean

true to specify that the GetPreamble() method returns a Unicode byte order mark; otherwise, false.

Examples

The following example creates a new UTF8Encoding instance and specifies that a Unicode byte order mark prefix should be emitted by the GetPreamble method. The GetPreamble method then returns the Unicode byte order mark prefix.

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        UTF8Encoding utf8 = new UTF8Encoding();
        UTF8Encoding utf8EmitBOM = new UTF8Encoding(true);

        Console.WriteLine("utf8 preamble:");
        ShowArray(utf8.GetPreamble());

        Console.WriteLine("utf8EmitBOM:");
        ShowArray(utf8EmitBOM.GetPreamble());
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine();
    }
}

Remarks

This constructor creates an instance that does not throw an exception when an invalid encoding is detected.

Caution

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

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.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

UTF8Encoding(Boolean, Boolean)

Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs
Source:
UTF8Encoding.cs

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.

public UTF8Encoding (bool encoderShouldEmitUTF8Identifier, bool throwOnInvalidBytes);

Parameters

encoderShouldEmitUTF8Identifier
Boolean

true to specify that the GetPreamble() method should return a Unicode byte order mark; otherwise, false.

throwOnInvalidBytes
Boolean

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

Examples

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 System;
using System.Text;

class Example
{
    public static void Main()
    {
        UTF8Encoding utf8 = new UTF8Encoding();
        UTF8Encoding utf8ThrowException = new UTF8Encoding(false, true);

        // Create an array with two high surrogates in a row (\uD801, \uD802).
        Char[] chars = new Char[] {'a', 'b', 'c', '\uD801', '\uD802', 'd'};

        // The following method call will not throw an exception.
        Byte[] bytes = utf8.GetBytes(chars);
        ShowArray(bytes);
        Console.WriteLine();

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

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray)
            Console.Write("{0:X2} ", o);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    61 62 63 EF BF BD EF BF BD 64
//
//    EncoderFallbackException exception
//    Message:
//    Unable to translate Unicode character \uD801 at index 3 to specified code page.

Remarks

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.

Caution

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

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0