UTF8Encoding.GetPreamble Metoda

Definice

Obor názvů:

System.Text

Sestavení:

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

Zdroj:

UTF8Encoding.cs

Vrátí znak pořadí bajtů Unicode kódovaný ve formátu UTF-8, pokud UTF8Encoding je objekt kódování nakonfigurovaný tak, aby ho mohl zadat.

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 UTF8Encoding je objekt kódování nakonfigurovaný 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 používá metodu GetPreamble k vrácení znaku pořadí pořadí kódování Unicode ve formátu UTF-8. Všimněte si, že konstruktor UTF8Encoding bez parametrů pro neposkytuje preambuli.

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

Následující příklad vytvoří instanci dvou UTF8Encoding objektů, první voláním konstruktoru bez UTF8Encoding() parametrů, který neposkytuje kusovník, a druhý voláním UTF8Encoding(Boolean) konstruktoru s argumentem encoderShouldEmitUTF8Identifier nastaveným na true. Potom volá metodu GetPreamble pro zápis kusovníku do souboru před zápisem řetězce s kódováním UF8. 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-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.

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 UTF-8, bom se nezobrazí.

Poznámky

Objekt UTF8Encoding může poskytnout preambuli, což je bajtové pole, které může být předponou posloupnosti bajtů, které jsou výsledkem procesu kódování. Prefacing sekvence zakó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. Značka pořadí bajtů Unicode (BOM) je serializována jako 0xEF 0xBB 0xBF. Mějte na paměti, že Standard Unicode nevyžaduje ani nedoporučuje použití kusovníku pro streamy kódování UTF-8.

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

• Načtením objektu UTF8Encoding vráceného Encoding.UTF8 vlastností.

• Zavoláním konstruktoru UTF8Encoding s parametrem encoderShouldEmitUTF8Identifier a nastavením jeho hodnoty na truehodnotu .

Všechny ostatní UTF8Encoding objekty jsou nakonfigurované tak, aby vracely prázdné pole místo platného kusovníku.

BoM poskytuje téměř určitou identifikaci kódování pro soubory, 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.

Další informace o pořadí bajtů a značce pořadí bajtů naleznete v tématu Standard Unicode na domovské stránce Unicode.

Důležité

Chcete-li zajistit, aby se kódované bajty správně dekódovaly, když jsou uloženy jako soubor nebo jako datový proud, můžete předponu začátku datového proudu kódovaných bajtů předponou predikce. 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.