UTF8Encoding.GetPreamble Метод

Ссылка

Определение

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

Сборка:: System.Text.Encoding.Extensions.dll

Сборка:: mscorlib.dll

Сборка:: netstandard.dll

Исходный код:: UTF8Encoding.cs

Исходный код:: UTF8Encoding.cs

Исходный код:: 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 namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(array<Byte>^ bytes)
{
   for each (Byte b in bytes)
      Console::Write( "{0:X2} ", b);

   Console::WriteLine();
}

int main()
{
   // The default constructor does not provide a preamble.
   UTF8Encoding^ UTF8NoPreamble = gcnew UTF8Encoding;
   UTF8Encoding^ UTF8WithPreamble = gcnew UTF8Encoding( true );
   array<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 );
}
// The example displays the following output:
//       UTF8NoPreamble
//        preamble length: 0
//        preamble:
//
//       UTF8WithPreamble
//        preamble length: 3
//        preamble: EF BB BF

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) конструктора с 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.

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.

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

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

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

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

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

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

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

Важно!

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

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

UTF8Encoding.GetPreamble Метод

Определение

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

Примеры

Комментарии

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

Обратная связь

Дополнительные ресурсы