UnicodeEncoding.GetPreamble Метод

Определение

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

System.Text

Сборки:

netstandard.dll, System.Text.Encoding.Extensions.dll

Исходный код:

UnicodeEncoding.cs

Возвращает метку порядка байтов Юникода, закодированную в формате 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 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 объектов, первый из которых не предоставляет BOM и второй из которых выполняется. Затем он вызывает GetPreamble метод для записи BOM в файл перед записью строки в кодировке Юникод. Как показано в выходных данных консоли, файл, который сохраняет байты из второго кодировщика, имеет три более байтов, чем первый.

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. Метка порядка байтов Юникода сериализуется следующим образом (в шестнадцатеричном формате):

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

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

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

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

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

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

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

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

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

Это важно

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