UnicodeEncoding.GetPreamble Метод

Определение

Возвращает метку порядка байтов Юникода, закодированную в формате UTF-16, если конструктор данного экземпляра запрашивает метку порядка байтов.Returns a Unicode byte order mark encoded in UTF-16 format, if the constructor for this instance requests a byte order mark.

public:
 override cli::array <System::Byte> ^ GetPreamble();
public override byte[] GetPreamble ();
override this.GetPreamble : unit -> byte[]
Public Overrides Function GetPreamble () As Byte()

Возвраты

Byte[]

Массив байтов, содержащий метку порядка байтов Юникода, если объект UnicodeEncoding настроен для его предоставления.A byte array containing the Unicode byte order mark, if the UnicodeEncoding object is configured to supply one. В противном случае этот метод возвращает массив байтов нулевой длины.Otherwise, this method returns a zero-length byte array.

Примеры

В следующем примере показано, как использовать GetPreamble метод, чтобы получить метку порядка байтов Юникода с обратным порядком байтов или с прямым порядком байт для экземпляра. UnicodeEncodingThe following example demonstrates how to use the GetPreamble method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a 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 объекта, первый из которых не предоставляет спецификацию, а вторая —.The following example instantiates two UnicodeEncoding objects, the first of which does not provide a BOM, and the second of which does. Затем он вызывает GetPreamble метод для записи спецификации в файл перед записью строки в кодировке Юникод.It then calls the GetPreamble method to write the BOM to a file before writing a Unicode-encoded string. Как видно из выходных данных консоли, файл, сохраняющий байты из второго кодировщика, имеет еще три байта, чем первый.As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first.

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 команды в окне консоли или просмотреть файлы в текстовом редакторе, содержащем шестнадцатеричный режим представления.You can also compare the files by using the fc command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Обратите внимание, что при открытии файла в редакторе, поддерживающем кодировку UTF-16, спецификация не отображается.Note that when the file is opened in an editor that supports UTF-16 encoding, the BOM is not displayed.

Комментарии

UnicodeEncoding Объект может предоставить преамбулу, которая представляет собой массив байтов, который может быть префиксом последовательности байтов, полученной в результате процесса кодирования.The UnicodeEncoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes resulting from the encoding process. Предустановление последовательности закодированных байтов с помощью метки порядка байтов (кодовая точка U + FEFF) помогает декодеру определить порядок байтов и формат преобразования или кодировку UTF.Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format or UTF. Метка порядка байтов Юникода (BOM) сериализуется следующим образом (в шестнадцатеричном формате):The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal):

  • Порядок байт с обратным порядком байтов: FE FFBig endian byte order: FE FF

  • Прямой порядок байтов: FF FELittle endian byte order: FF FE

Можно создать экземпляр UnicodeEncoding объекта, метод которого GetPreamble Возвращает действительную спецификацию, следующим образом.You can instantiate a UnicodeEncoding object whose GetPreamble method returns a valid BOM in the following ways:

Мы рекомендуем использовать СПЕЦИФИКАЦИю, так как она обеспечивает почти определенную идентификацию кодировки для файлов, которые в противном случае теряют ссылку на их кодировку, такую как непомеченные или неправильно помеченные веб-данные или случайные текстовые файлы, хранящиеся, если у бизнеса нет международные проблемы.We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Часто проблемы пользователей могут быть устранены, если данные постоянно и правильно помечены тегами.Often user problems might be avoided if data is consistently and properly tagged.

Для стандартов, предоставляющих тип кодировки, BOM является несколько избыточным.For standards that provide an encoding type, a BOM is somewhat redundant. Однако его можно использовать, чтобы помочь серверу отправить правильный заголовок кодировки.However, it can be used to help a server send the correct encoding header. Кроме того, его можно использовать в качестве резервного, если кодировка в противном случае будет потеряна.Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

Существует ряд недостатков использования спецификации.There are some disadvantages to using a BOM. Например, знание того, как ограничить поля базы данных, использующие СПЕЦИФИКАЦИю, может оказаться затруднительным.For example, knowing how to limit the database fields that use a BOM can be difficult. Объединение файлов может быть проблемой, например, при слиянии файлов таким образом, что ненужный символ может оказаться в середине данных.Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Несмотря на множество недостатков, настоятельно рекомендуется использовать СПЕЦИФИКАЦИю.In spite of the few disadvantages, however, the use of a BOM is highly recommended.

Важно!

Чтобы обеспечить правильную декодирование закодированных байтов, следует добавить в начало потока закодированных байтов префикс в виде преамбулы.To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Обратите внимание GetBytes , что метод не добавляет к последовательности закодированных байтов спецификацию. Указание спецификации в начале соответствующего потока байтов является обязанностью разработчика.Note that the GetBytes method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility.

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