Encoding.Preamble Property

Definition

Namespace:

System.Text

Assembly:

System.Runtime.dll

Source:

Encoding.cs

When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used.

public:
 virtual property ReadOnlySpan<System::Byte> Preamble { ReadOnlySpan<System::Byte> get(); };

public virtual ReadOnlySpan<byte> Preamble { get; }

member this.Preamble : ReadOnlySpan<byte>

Public Overridable ReadOnly Property Preamble As ReadOnlySpan(Of Byte)

Property Value

ReadOnlySpan<Byte>

A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required.

Remarks

Optionally, the Encoding object provides a preamble that is an sequence of bytes that can be prefixed to the bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF.

The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal):

• UTF-8: EF BB BF

• UTF-16 big endian byte order: FE FF

• UTF-16 little endian byte order: FF FE

• UTF-32 big endian byte order: 00 00 FE FF

• UTF-32 little endian byte order: FF FE 00 00

You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the Encoding object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16.

For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Despite the few disadvantages, however, the use of a BOM is highly recommended.

For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

Caution

To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, UTF8Encoding, UnicodeEncoding, or UTF32Encoding, with a preamble.