UnicodeEncoding.GetPreamble 方法

参考

定义

命名空间:: System.Text

程序集:: System.Text.Encoding.Extensions.dll

程序集:: mscorlib.dll

程序集:: netstandard.dll

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

如果此实例的构造函数请求一个字节顺序标记，则将返回用 UTF-16 格式编码的 Unicode 字节顺序标记。

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

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Byte[]

一个包含 Unicode 字节顺序标记的字节数组（如果 UnicodeEncoding 对象配置为提供一个这样的字节数组）。否则，此方法返回一个零长度的字节数组。

示例

下面的示例演示了如何使用GetPreamble该方法检索大尾号或小尾字节顺序中的 Unicode 字节顺序标记。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 个对象，其中第一个对象不提供 BOM，第二个对象会实例化。然后，它会调用 GetPreamble 该方法，在编写 Unicode 编码的字符串之前将 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。 Unicode 字节顺序标记（BOM）按以下方式序列化（十六进制）：

大尾字节顺序： FE FF
小尾字节顺序： FF FE

可以实例化UnicodeEncoding对象，其GetPreamble方法按以下方式返回有效的 BOM：

通过检索UnicodeEncoding或Encoding.BigEndianUnicode属性返回Encoding.Unicode的对象。
通过调用无 UnicodeEncoding() 参数构造函数来实例化 UnicodeEncoding 对象。
通过将参数UnicodeEncoding(Boolean, Boolean)的值byteOrderMark提供给或UnicodeEncoding(Boolean, Boolean, Boolean)构造函数来提供true。

建议使用 BOM，因为它为文件提供几乎确定的编码标识，否则会丢失对其编码的引用，如未标记或未标记的 Web 数据或随机文本文件（如果企业没有国际关注）。如果数据一致且正确标记，则通常避免用户问题。

对于提供编码类型的标准，BOM 有些多余。但是，可以使用它来帮助服务器发送正确的编码标头。或者，它可以用作回退，以防编码在其他情况下丢失。

使用 BOM 存在一些缺点。例如，了解如何限制使用 BOM 的数据库字段可能很困难。文件的串联可能也是一个问题，例如，当文件以这样一种方式进行合并时，不需要的字符会在数据中间结束。但尽管有几个缺点，但强烈建议使用 BOM。

重要

若要确保已编码的字节正确解码，应为编码字节流的开头加上前缀。请注意，该方法 GetBytes 不会将 BOM 追加到编码字节序列;在适当的字节流的开头提供 BOM 是开发人员的责任。

适用于

UnicodeEncoding.GetPreamble 方法

定义

返回

示例

注解

适用于

其他资源