UTF8Encoding.GetPreamble Метод

Определение

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

System.Text

Сборки:

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

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

UTF8Encoding.cs

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

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

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

Byte[]

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

Примеры

В следующем примере метод используется GetPreamble для возврата метки порядка байтов Юникода, закодированной в формате UTF-8. Обратите внимание, что конструктор без параметров для UTF8Encoding не предоставляет преамбл.

using System;
using System.Text;

class Example
{
    public static void Main()
    {
        // The default constructor does not provide a preamble.
        UTF8Encoding UTF8NoPreamble = new UTF8Encoding();
        UTF8Encoding UTF8WithPreamble = new UTF8Encoding(true);

        Byte[] preamble;

        preamble = UTF8NoPreamble.GetPreamble();
        Console.WriteLine("UTF8NoPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
        Console.WriteLine();
        
        preamble = UTF8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
    }

    public static void ShowArray(Byte[] bytes)
    {
        foreach (var b in bytes)
            Console.Write("{0:X2} ", b);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    UTF8NoPreamble
//     preamble length: 0
//     preamble:
//
//    UTF8WithPreamble
//     preamble length: 3
//     preamble: EF BB BF

Imports System.Text

Module Example
    Public Sub Main()
        ' The default constructor does not provide a preamble.
        Dim UTF8NoPreamble As New UTF8Encoding()
        Dim UTF8WithPreamble As New UTF8Encoding(True)
        
        Dim preamble() As Byte
        
        preamble = UTF8NoPreamble.GetPreamble()
        Console.WriteLine("UTF8NoPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
        Console.WriteLine()
        
        preamble = UTF8WithPreamble.GetPreamble()
        Console.WriteLine("UTF8WithPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
    End Sub

    Public Sub ShowArray(bytes As Byte())
        For Each b In  bytes
            Console.Write("{0:X2} ", b)
        Next
        Console.WriteLine()
    End Sub
End Module
' The example displays the following output:
'    UTF8NoPreamble
'     preamble length: 0
'     preamble:
'
'    UTF8WithPreamble
'     preamble length: 3
'     preamble: EF BB BF

В следующем примере создается экземпляр двух UTF8Encoding объектов, первый путем вызова конструктора без UTF8Encoding() параметров, который не предоставляет BOM, а второй путем вызова UTF8Encoding(Boolean) конструктора с заданным encoderShouldEmitUTF8Identifiertrueаргументом. Затем он вызывает GetPreamble метод для записи BOM в файл перед записью строки в кодировке UF8. Как показано в выходных данных консоли, файл, который сохраняет байты из второго кодировщика, имеет три более байтов, чем первый.

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-8 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF8Encoding();
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile("NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF8Encoding(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 57 bytes to NoPreamble.txt.
//
//       Preamble has 3 bytes
//       Wrote 60 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-8 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF8Encoding()
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF8Encoding(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 57 bytes to NoPreamble.txt.
'
'       Preamble has 3 bytes
'       Wrote 60 bytes to Preamble.txt.

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

Комментарии

Объект UTF8Encoding может предоставить преамблирование, который представляет собой массив байтов, который можно префиксировать в последовательность байтов, результатом которого является процесс кодирования. Префиксирование последовательности закодированных байтов с меткой порядка байтов (кодовая точка U+FEFF) помогает декодировщику определить порядок байтов и формат преобразования или UTF. Метка порядка байтов Юникода сериализуется как 0xEF 0xBB 0xBF. Обратите внимание, что Стандарт Юникода не требует и не рекомендует использовать BOM для потоков в кодировке UTF-8.

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

• Извлекая объект, UTF8Encoding возвращаемый свойством Encoding.UTF8 .

• Вызывая конструктор с параметром UTF8Encoding и задав для нее encoderShouldEmitUTF8Identifier значение true.

Все остальные UTF8Encoding объекты настроены для возврата пустого массива, а не допустимого BOM.

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

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

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

Дополнительные сведения о порядке байтов и отметке порядка байтов см. в разделе "Стандартный юникод" на домашней странице юникода .

Это важно

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