UTF8Encoding.GetPreamble Метод

Определение

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

public override byte[] GetPreamble ();

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

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

В следующем примере создается экземпляр двух UTF8Encoding объектов: первый путем вызова конструктора без UTF8Encoding() параметров, который не предоставляет BOM, а второй — путем вызова UTF8Encoding(Boolean) конструктора с encoderShouldEmitUTF8Identifier аргументом , равным true. Затем он вызывает 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.

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

Комментарии

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

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

  • Путем получения объекта, UTF8Encoding возвращаемого свойством Encoding.UTF8 .

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

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

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

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

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

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

Важно!

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

Применяется к

Продукт Версии
.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