UnicodeEncoding.GetPreamble Metódus

Definíció

Névtér:

System.Text

Szerelvények:

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

Forrás:

UnicodeEncoding.cs

UTF-16 formátumban kódolt Unicode bájtsorrend-jelet ad vissza, ha a példány konstruktora bájtsorrendjelet kér.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Válaszok

Byte[]

Unicode bájtsorrendjelet tartalmazó bájttömb, ha az UnicodeEncoding objektum úgy van konfigurálva, hogy adjon meg egyet. Ellenkező esetben ez a metódus nulla hosszúságú bájttömböt ad vissza.

Példák

Az alábbi példa bemutatja, hogyan lehet a GetPreamble metódussal lekérni a Unicode bájtsorrendjelet big endian vagy little endian byte sorrendben egy UnicodeEncodingpéldányhoz.

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

Az alábbi példa két UnicodeEncoding objektumot hoz létre, amelyek közül az első nem ad meg anyagjegyzéket, a második pedig igen. Ezután meghívja a metódust, GetPreamble hogy írja a BOM-t egy fájlba, mielőtt unicode-kódolt sztringet ír. Ahogy a példa konzolkimenete is mutatja, a második kódolóból a bájtokat menteni kívánt fájlnak három bájtja van, mint az elsőnek.

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.

A fájlokat fc a konzolablakban található paranccsal is összehasonlíthatja, vagy hexa nézet módban lévő szövegszerkesztőben is megvizsgálhatja a fájlokat. Vegye figyelembe, hogy ha a fájl olyan szerkesztőben van megnyitva, amely támogatja az UTF-16 kódolást, a BOM nem jelenik meg.

Megjegyzések

Az UnicodeEncoding objektum megadhat egy preambulumot, amely egy bájttömb, amely előtaggal rendelkezik a kódolási folyamatból eredő bájtok sorozatához. A kódolt bájtok sorozatának előbontása bájtsorrendjellel (U+FEFF kódpont) segít a dekódolónak meghatározni a bájtsorrendet és az átalakítási formátumot vagy az UTF-et. A Unicode byte order mark (BOM) szerializálva van az alábbiak szerint (hexadecimális):

• Big endian byte order: FE FF

• Kis endian bájtsorrend: FF FE

Az alábbi módokon példányosíthat egy UnicodeEncoding objektumot, amelynek GetPreamble metódusa érvényes anyagjegyzéket ad vissza:

• Az objektum vagy UnicodeEncoding tulajdonság Encoding.Unicode által Encoding.BigEndianUnicode visszaadott objektum beolvasásával.

• A paraméter nélküli UnicodeEncoding() konstruktor meghívásával példányosíthat egy objektumot UnicodeEncoding .

• Ha az argumentum értékeként adja meg true a byteOrderMark konstruktoroknak vagy UnicodeEncoding(Boolean, Boolean) konstruktoroknakUnicodeEncoding(Boolean, Boolean, Boolean).

Javasoljuk, hogy használja a BOM-t, mivel szinte biztosan azonosítja az olyan fájlok kódolását, amelyek egyébként elvesztették a kódolásukra való hivatkozást, például a címkézetlen vagy helytelenül címkézett webes adatokat vagy a véletlenszerű szöveges fájlokat, amelyek akkor vannak tárolva, ha egy vállalat nem rendelkezik nemzetközi aggályokkal. Gyakran elkerülhetők a felhasználói problémák, ha az adatok következetesen és megfelelően vannak címkézve.

A kódolási típust biztosító szabványok esetében a BOM némileg redundáns. Ezzel azonban segíthet a kiszolgálónak a megfelelő kódolási fejléc küldésében. Alternatív megoldásként tartalékként is használható, ha a kódolás egyébként elveszik.

A BOM használatának néhány hátránya van. Nehéz lehet például tudni, hogyan korlátozhatja az AJ-t használó adatbázismezőket. A fájlok összefűzése problémát jelenthet például a fájlok egyesítésekor oly módon, hogy egy szükségtelen karakter az adatok közepén végződjön. A kevés hátrány ellenére azonban erősen ajánlott az anyagjegyzék használata.

Important

Annak érdekében, hogy a kódolt bájtok megfelelően legyenek dekódolva, előtaggal kell ellátnia a kódolt bájtok adatfolyamának elejét egy preambulummal. Vegye figyelembe, hogy a GetBytes módszer nem használja fel előre a BOM-t kódolt bájtok sorozatára; a megfelelő bájtfolyam elején a BOM átadása a fejlesztő feladata.