UTF32Encoding.GetPreamble Metódus

Definíció

Névtér:

System.Text

Szerelvények:

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

Forrás:

UTF32Encoding.cs

UTF-32 formátumban kódolt Unicode bájtsorrend-jelet ad vissza, ha az UTF32Encoding objektum úgy van konfigurálva, hogy adjon meg egyet.

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 UTF32Encoding 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éldakód lekéri és megjeleníti a különböző UTF32Encoding példányok bájtsorrendjelét.

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   Public Shared Sub PrintHexBytes(bytes() As Byte)
      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else
         Dim i As Integer
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If
   End Sub
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

Az alábbi példa két UTF32Encoding objektumot hoz létre, amelyek közül az első nem ad AJ-t, a második pedig igen. Ezután meghívja a metódust, GetPreamble hogy írja a BOM-t egy fájlba, mielőtt egy UTF-32 kódolású sztringet ír. Ahogy a példa kimenete is mutatja, a második kódolóból a bájtokat menteni kívánt fájlnak négy további bájtja van.

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-32 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF32Encoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF32Encoding(! 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 232 bytes to .\NoPreamble.txt.
//
//       Preamble has 4 bytes
//       Wrote 236 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-32 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF32Encoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF32Encoding(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 232 bytes to NoPreamble.txt.
'
'       Preamble has 4 bytes
'       Wrote 236 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ájlt egy UTF-32-t támogató szerkesztőben nyitja meg, a BOM nem jelenik meg.

Megjegyzések

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

• Big endian byte order: 00 00 FE FF

• Kis endian bájtsorrend: FF FE 00 00

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

• A tulajdonság által UTF32Encoding visszaadott objektum beolvasásávalEncoding.UTF32.

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

• Azáltal, hogy true az argumentum értékeként adja meg a byteOrderMark konstruktorokat és UTF32Encoding a UTF32Encoding konstruktorokat.

Javasoljuk, hogy használja a BOM-t, mivel szinte biztosan azonosítja az olyan fájlok kódolását, amelyek egyébként nem hivatkoztak UTF32Encoding az objektumra, például címkézetlen vagy helytelenül címkézett webes adatokra, vagy véletlenszerű szöveges fájlokra, amelyek akkor vannak tárolva, amikor egy vállalat nem rendelkezik nemzetközi aggályokkal vagy más adatokkal. 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.

A bájtsorrendről és a bájtsorrendjelről további információt a Unicode Standard Unicode kezdőlapjántalál.

Important

Annak érdekében, hogy a kódolt bájtok megfelelően legyenek dekódolva, előre kódolt bájtokat kell előtaggal ellátnia. 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.