UnicodeEncoding.GetPreamble Metoda

Reference

Definice

Obor názvů:: System.Text

Sestavení:: System.Text.Encoding.Extensions.dll

Sestavení:: mscorlib.dll

Sestavení:: netstandard.dll

Důležité

Některé informace platí pro předběžně vydaný produkt, který se může zásadně změnit, než ho výrobce nebo autor vydá. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Vrátí značku pořadí bajtů Unicode zakó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[]

Pole bajtů obsahující značku pořadí bajtů Unicode, pokud UnicodeEncoding je objekt 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 ukazuje, jak použít metodu GetPreamble k načtení značky pořadí bajtů Unicode v big endian nebo little endian bajt pořadí pro instanci UnicodeEncoding.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

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 druhou z toho. Potom zavolá metodu pro GetPreamble 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 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-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 porovnat také pomocí fc příkazu v okně konzoly nebo můžete soubory zkontrolovat v textovém editoru, který obsahuje režim zobrazení šestnáctkového 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 předponu bajtů, 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ů (kódový bod U+FEFF) pomáhá dekodér určit pořadí bajtů a formát transformace nebo UTF. Značka pořadí bajtů Unicode (BOM) je serializována následujícím způsobem (v šestnáctkové soustavě):

Pořadí velkých bajtů: FE FF
Pořadí malých bajtů: FF FE

Instanci objektu UnicodeEncoding , jehož GetPreamble metoda vrací platný kusovník, můžete vytvořit instanci následujícím způsobem:

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 .
Zadáním true hodnoty argumentu byteOrderMark nebo UnicodeEncoding(Boolean, Boolean, Boolean) konstruktorůmUnicodeEncoding(Boolean, Boolean).

Doporučujeme použít boM, protože 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á 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 boM poněkud redundantní. Dá se ale použít k tomu, aby server odeslal správnou hlavičku kódování. Alternativně se dá použít jako záložní v případě, že je kódování jinak ztraceno.

Používání kusovníku má určité nevýhody. Znalost omezení databázových polí, která používají kusovník, může být například obtížné. Zřetězení souborů může být také problém, například když jsou soubory sloučeny 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.