UnicodeEncoding.GetPreamble Metoda

Definice

Obor názvů:

System.Text

Sestavení:

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

Zdroj:

UnicodeEncoding.cs

Vrátí značku pořadí bajtů Unicode kódovanou ve formátu UTF-16, pokud konstruktor pro tuto instanci požaduje značku pořadí bajtů.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Návraty

Byte[]

Bajtové pole obsahující značku pořadí bajtů Unicode, pokud UnicodeEncoding je objekt nakonfigurován tak, aby ho mohl zadat. V opačném případě tato metoda vrátí pole bajtů nulové délky.

Příklady

Následující příklad ukazuje, jak použít metodu GetPreamble k načtení znaku pořadí pořadí bajtů Unicode v big endian nebo little endian byte pořadí pro instanci UnicodeEncoding.

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

Následující příklad vytvoří instanci dvou UnicodeEncoding objektů, z nichž první neposkytuje kusovník a druhý objekt. Potom volá metodu GetPreamble pro zápis kusovníku do souboru před zápisem řetězce kódování Unicode. Jak ukazuje výstup konzoly z příkladu, soubor, který ukládá bajty z druhého kodéru, má tři více bajtů než první.

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.

Soubory můžete také porovnat pomocí fc příkazu v okně konzoly nebo můžete zkontrolovat soubory v textovém editoru, který obsahuje šestnáctkový režim zobrazení. Všimněte si, že když je soubor otevřen v editoru, který podporuje kódování UTF-16, boM se nezobrazí.

Poznámky

Objekt UnicodeEncoding může poskytnout preambuli, což je bajtové pole, které může být předponou posloupnosti bajtů vyplývajících z procesu kódování. Prefacing sekvence kódovaných bajtů se značkou pořadí bajtů (bod kódu U+FEFF) pomáhá dekodéru určit pořadí bajtů a formát transformace nebo UTF. Znak pořadí bajtů Unicode (BOM) je serializován následujícím způsobem (v šestnáctkové soustavě):

• Pořadí velkých endiánských bajtů: FE FF

• Malé pořadí bajtů endian: FF FE

Můžete vytvořit instanci objektu UnicodeEncoding , jehož GetPreamble metoda vrátí platnou bom následujícími způsoby:

• Načtením objektu UnicodeEncoding vráceného objektem Encoding.Unicode nebo Encoding.BigEndianUnicode vlastností.

• Voláním konstruktoru bez UnicodeEncoding() parametrů vytvořte instanci objektu UnicodeEncoding .

• true Zadáním hodnoty argumentu byteOrderMark konstruktorůmUnicodeEncoding(Boolean, Boolean).UnicodeEncoding(Boolean, Boolean, Boolean)

Doporučujeme použít kusovník, protože poskytuje téměř určitou identifikaci kódování souborů, které jinak ztratily odkaz na jejich kódování, například neoznačené nebo nesprávně označené webové data nebo náhodné textové soubory uložené v případě, že firma neměla mezinárodní obavy. Problémy uživatelů se často můžou vyhnout, pokud jsou data konzistentně a správně označená.

Pro standardy, které poskytují typ kódování, je kusovník poněkud redundantní. Dá se ale použít k tomu, aby server posílal správnou hlavičku kódování. Alternativně se dá použít jako záložní v případě, že se kódování jinak ztratí.

Používání kusovníku má určité nevýhody. Například znalost omezení databázových polí, která používají kusovník, může být obtížné. Zřetězení souborů může být také problém, například když se soubory sloučí tak, aby nepotřebný znak mohl skončit uprostřed dat. I přes několik nevýhod se však důrazně doporučuje použití kusovníku.

Důležité

Chcete-li zajistit, aby kódované bajty byly dekódovány správně, měli byste předponu začátku datového proudu kódovaných bajtů predálitem. Všimněte si, že GetBytes metoda nepředkládá kusovník na sekvenci kódovaných bajtů; poskytnutí kusovníku na začátku příslušného bajtového streamu je zodpovědností vývojáře.