UnicodeEncoding.GetPreamble Метод

Определение

Пространство имен:

System.Text

Сборка:

System.Text.Encoding.Extensions.dll

Сборка:

mscorlib.dll

Сборка:

netstandard.dll

Возвращает метку порядка байтов Юникода, закодированную в формате UTF-16, если конструктор данного экземпляра запрашивает метку порядка байтов.

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Возвращаемое значение

Byte[]

Массив байтов, содержащий метку порядка байтов Юникода, если объект UnicodeEncoding настроен для его предоставления. В противном случае этот метод возвращает массив байтов нулевой длины.

Примеры

В следующем примере показано, как использовать GetPreamble метод для получения метки порядка байтов Юникода в большом байтовом или маленьком байтовом порядке для экземпляра объекта UnicodeEncoding.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Byte[] byteOrderMark;
        
        byteOrderMark = Encoding.Unicode.GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine("\n");

        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
    }
}

Imports System.Text

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim byteOrderMark() As Byte
        Dim b As Byte
        
        byteOrderMark = Encoding.Unicode.GetPreamble()
        Console.WriteLine("Default (little-endian) Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine(ControlChars.NewLine)
        
        Dim bigEndianUnicode As New UnicodeEncoding(True, True)
        byteOrderMark = bigEndianUnicode.GetPreamble()
        Console.WriteLine("Big-endian Unicode Preamble:")
        For Each b In  byteOrderMark
            Console.Write("[{0}]", b)
        Next b
    End Sub
End Class

В следующем примере создается экземпляр двух UnicodeEncoding объектов, первый из которых не предоставляет метку байтов и второй из которых выполняется. Затем он вызывает GetPreamble метод записи метки в файл перед записью строки в кодировке Юникод. Как показано в выходных данных консоли из примера, файл, сохраняющий байты из второго кодировщика, имеет более трех байтов, чем первый.

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
      String s = "This is a string to write to a file using UTF-16 encoding.";

      // Write a file using a Unicode encoding object without a BOM.
      var enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UnicodeEncoding(! BitConverter.IsLittleEndian, true);
      WriteToFile(@".\Preamble.txt", enc, bytes);
   }

   private static void WriteToFile(String fn, Encoding enc, Byte[] bytes)
   {
      var fs = new FileStream(fn, FileMode.Create);
      Byte[] preamble = enc.GetPreamble();
      fs.Write(preamble, 0, preamble.Length);
      Console.WriteLine("Preamble has {0} bytes", preamble.Length);
      fs.Write(bytes, 0, bytes.Length);
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn);
      fs.Close();
      Console.WriteLine();
   }
}
// The example displays the following output:
//       Preamble has 0 bytes
//       Wrote 116 bytes to .\NoPreamble.txt.
//
//       Preamble has 2 bytes
//       Wrote 118 bytes to .\Preamble.txt.

Imports System.IO
Imports System.Text

Module Example
   Public Sub Main()
      Dim s As String = "This is a string to write to a file using UTF-16 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UnicodeEncoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UnicodeEncoding(Not BitConverter.IsLittleEndian, True)
      WriteToFile("Preamble.txt", enc, bytes)
   End Sub

   Private Sub WriteToFile(fn As String, enc As Encoding, bytes As Byte())
      Dim fs As New FileStream(fn, FileMode.Create)
      Dim preamble() As Byte = enc.GetPreamble()
      fs.Write(preamble, 0, preamble.Length)
      Console.WriteLine("Preamble has {0} bytes", preamble.Length)
      fs.Write(bytes, 0, bytes.Length)
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn)
      fs.Close()
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'       Preamble has 0 bytes
'       Wrote 116 bytes to .\NoPreamble.txt.
'
'       Preamble has 2 bytes
'       Wrote 118 bytes to .\Preamble.txt.

Вы также можете сравнить файлы с помощью fc команды в окне консоли или проверить файлы в текстовом редакторе, который включает режим шестнадцатеричного представления. Обратите внимание, что при открытии файла в редакторе, поддерживающем кодировку UTF-16, BOM не отображается.

Комментарии

Объект UnicodeEncoding может предоставить преамблирование, который является массивом байтов, который можно префиксировать в последовательность байтов, полученных из процесса кодирования. Подготовка последовательности закодированных байтов с меткой порядка байтов (кодовая точка U+FEFF) помогает декодеру определить порядок байтов и формат преобразования или UTF. Метка порядка байтов Юникода (BOM) сериализуется следующим образом (в шестнадцатеричном формате):

• Порядок байтов большого байта: FE FF

• Маленький порядок байтов байтов: FF FE

Вы можете создать UnicodeEncoding экземпляр объекта, метод которого GetPreamble возвращает допустимую метку байтов следующими способами:

• Извлекая объект, UnicodeEncoding возвращаемый свойством Encoding.Unicode или Encoding.BigEndianUnicode объектом.

• Вызов конструктора без UnicodeEncoding() параметров для создания экземпляра UnicodeEncoding объекта.

• Путем предоставления true в качестве значения аргумента byteOrderMark UnicodeEncoding(Boolean, Boolean) конструктора или UnicodeEncoding(Boolean, Boolean, Boolean) конструкторам.

Мы рекомендуем использовать BOM, так как он обеспечивает почти определенную идентификацию кодировки для файлов, которые в противном случае потеряли ссылку на их кодировку, такие как несмежные или неправильно помеченные веб-данные или случайные текстовые файлы, хранящиеся, когда бизнес не имеет международных проблем. Часто проблемы с пользователем могут быть избежать, если данные последовательно и правильно помечены.

Для стандартов, предоставляющих тип кодировки, BOM является несколько избыточным. Однако его можно использовать, чтобы помочь серверу отправить правильный заголовок кодировки. Кроме того, его можно использовать в качестве резервного, если кодировка в противном случае будет потеряна.

Существует ряд недостатков использования спецификации. Например, знание того, как ограничить поля базы данных, использующие СПЕЦИФИКАЦИю, может оказаться затруднительным. Объединение файлов может быть проблемой, например, при слиянии файлов таким образом, что ненужный символ может оказаться в середине данных. Несмотря на множество недостатков, настоятельно рекомендуется использовать СПЕЦИФИКАЦИю.

Важно!

Чтобы убедиться, что закодированные байты декодированы правильно, следует префиксировать начало потока закодированных байтов с префиксом. Обратите внимание, что GetBytes метод не добавляет метку байтов в последовательность закодированных байтов; предоставление BOM в начале соответствующего потока байтов является ответственностью разработчика.