UTF8Encoding.GetPreamble Metódus

Definíció

Névtér:

System.Text

Szerelvények:

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

Forrás:

UTF8Encoding.cs

UTF-8 formátumban kódolt Unicode bájtsorrend-jelet ad vissza, ha a UTF8Encoding kódolási 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[]

A Unicode bájtsorrendjelet tartalmazó bájttömb, ha a UTF8Encoding kódolási 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 az UTF-8 formátumban kódolt Unicode bájtsorrendjel visszaadására használja a GetPreamble metódust. Figyelje meg, hogy a paraméter nélküli konstruktor UTF8Encoding nem tartalmaz preambulumot.

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

Az alábbi példa két UTF8Encoding objektumot példányosít, az első a paraméter nélküli UTF8Encoding() konstruktor meghívásával, amely nem ad AJ-t, a második pedig a UTF8Encoding(Boolean) konstruktort az argumentumának encoderShouldEmitUTF8Identifier beállításával true. Ezután meghívja a metódust, GetPreamble hogy írja a BOM-t egy fájlba, mielőtt egy UF8 kódolású 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-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.

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 egy UTF-8-t támogató szerkesztőben van megnyitva, a BOM nem jelenik meg.

Megjegyzések

Az UTF8Encoding 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, vagyis az UTF-et. A Unicode byte order mark (BOM) szerializálva van 0xEF 0xBB 0xBF. Vegye figyelembe, hogy a Unicode Standard nem követeli meg és nem is javasolja a BOM használatát az UTF-8 kódolású streamekhez.

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

• A tulajdonság által UTF8Encoding visszaadott objektum beolvasásávalEncoding.UTF8.

• Egy konstruktor paraméterrel való meghívásával UTF8EncodingencoderShouldEmitUTF8Identifier és értékének beállításával true.

Minden más UTF8Encoding objektum úgy van konfigurálva, hogy egy üres tömböt adjon vissza érvényes anyagjegyzék helyett.

A BOM szinte biztosan azonosítja a kódolást az olyan fájlok esetében, 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övegfájlokat, amelyek akkor vannak tárolva, ha egy vállalkozás nem rendelkezik nemzetközi problémákkal. 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, amikor fájlként vagy streamként vannak mentve, előtaggal adhatja meg 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.