UTF8Encoding.GetPreamble Metoda

Definice

Obor názvů:

System.Text

Sestavení:

System.Text.Encoding.Extensions.dll

Zdroj:

UTF8Encoding.cs

Vrátí znak pořadí bajtů Unicode zakódovaný ve formátu UTF-8, pokud UTF8Encoding je kódovací objekt nakonfigurován tak, aby jednu zadává.

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[]

Pole bajtů obsahující značku pořadí bajtů Unicode, pokud UTF8Encoding je kódovací objekt nakonfigurován tak, aby ji zadává. V opačném případě tato metoda vrátí pole nulové délky bajtů.

Příklady

Následující příklad používá metodu GetPreamble k vrácení značky pořadí bajtů Unicode zakódované ve formátu UTF-8. Všimněte si, že konstruktor bez parametrů pro UTF8Encoding neposkytuje preambuli.

using namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(array<Byte>^ bytes)
{
   for each (Byte b in bytes)
      Console::Write( "{0:X2} ", b);

   Console::WriteLine();
}

int main()
{
   // The default constructor does not provide a preamble.
   UTF8Encoding^ UTF8NoPreamble = gcnew UTF8Encoding;
   UTF8Encoding^ UTF8WithPreamble = gcnew UTF8Encoding( true );
   array<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 );
}
// The example displays the following output:
//       UTF8NoPreamble
//        preamble length: 0
//        preamble:
//
//       UTF8WithPreamble
//        preamble length: 3
//        preamble: EF BB BF

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 konstruktoru UTF8Encoding(Boolean) s argumentem encoderShouldEmitUTF8Identifier nastaveným na true. Potom zavolá metodu GetPreamble zápisu kusovníku do souboru před zápisem řetězce kódovaného UF8. Jak ukazuje výstup konzoly z příkladu, soubor, který ukládá bajty z druhého kodéru, má o tři bajty více 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 je můžete zkontrolovat v textovém editoru, který obsahuje režim šestnáctkového zobrazení. Všimněte si, že při otevření souboru v editoru, který podporuje UTF-8, se kusovník nezobrazí.

Poznámky

Objekt UTF8Encoding může poskytnout preambuli, což je pole bajtů, které může být předponou posloupnosti bajtů, které jsou výsledkem procesu kódování. Prefekce posloupnosti 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 neboli UTF. Značka pořadí bajtů unicode je serializována jako 0xEF 0xBB 0xBF. Všimněte si, ž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 vrací platný kusovník následujícími způsoby:

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

• Volá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.

Kusovník poskytuje téměř určitou identifikaci kódování pro soubory, které jinak ztratily odkaz na své kódování, například neoznačovaná 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 dají 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 odeslal správnou hlavičku kódování. Případně se dá použít jako záložní v případě, že by se kódování jinak ztratilo.

Použití 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 při sloučení souborů takovým způsobem, že nepotřebný znak může 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ů najdete v tématu Standard Unicode na domovské stránce sady Unicode.

Důležité

Abyste zajistili, že se zakódované bajty správně dekódují při uložení jako soubor nebo jako datový proud, můžete před začátek streamu kódovaných bajtů zadat předponu preambule. Všimněte si, že GetBytes metoda nepředkládá kusovník na sekvenci zakódovaných bajtů. Za poskytnutí kusovníku na začátku příslušného bajtového datového proudu zodpovídá vývojář.