UnicodeEncoding.GetPreamble Metod

Definition

Namnområde:

System.Text

Sammansättning:

mscorlib.dll

Returnerar ett Unicode-byteordningsmärke som är kodat i UTF-16-format, om konstruktorn för den här instansen begär ett byteordningsmärke.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Returer

Byte[]

En bytematris som innehåller Unicode-byteordningsmarkeringen UnicodeEncoding om objektet är konfigurerat att ange en. Annars returnerar den här metoden en bytematris med noll längd.

Exempel

I följande exempel visas hur du använder GetPreamble metoden för att hämta Unicode-byteordningsmarkeringen i stor endiansk eller lite endiansk byteordning för en instans av en 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

I följande exempel instansieras två UnicodeEncoding objekt, varav det första inte tillhandahåller någon strukturliste, och det andra gör det. Sedan anropas GetPreamble metoden för att skriva bommen till en fil innan du skriver en Unicode-kodad sträng. Som konsolens utdata från exemplet visar har filen som sparar byte från den andra kodaren tre fler byte än den första.

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.

Du kan också jämföra filerna med hjälp fc av kommandot i ett konsolfönster, eller så kan du granska filerna i en textredigerare som innehåller ett Hex-vyläge. Observera att när filen öppnas i ett redigeringsprogram som stöder UTF-16-kodning visas inte strukturlistan.

Kommentarer

Objektet UnicodeEncoding kan ange en ingress, som är en bytematris som kan prefixeras till sekvensen med byte som är resultatet av kodningsprocessen. Genom att föregå en sekvens med kodade byte med ett byteordningsmärke (kodpunkten U+FEFF) kan avkodaren fastställa byteordningen och transformeringsformatet eller UTF. Unicode byte order mark (BOM) serialiseras på följande sätt (i hexadecimal):

• Stor endiansk byteordning: FE FF

• Lite endiansk byteordning: FF FE

Du kan instansiera ett UnicodeEncoding objekt vars GetPreamble metod returnerar en giltig strukturlista på följande sätt:

• Genom att hämta objektet UnicodeEncoding som returneras av Encoding.Unicode egenskapen eller Encoding.BigEndianUnicode .

• Genom att anropa den parameterlösa UnicodeEncoding() konstruktorn för att instansiera ett UnicodeEncoding objekt.

• Genom att true ange som värdet för byteOrderMark argumentet till UnicodeEncoding(Boolean, Boolean) konstruktorerna eller UnicodeEncoding(Boolean, Boolean, Boolean) .

Vi rekommenderar att du använder bommen eftersom den ger nästan viss identifiering av en kodning för filer som annars har förlorat en referens till deras kodning, till exempel otaggade eller felaktigt taggade webbdata eller slumpmässiga textfiler som lagras när ett företag inte har internationella problem. Ofta kan användarproblem undvikas om data är konsekventa och korrekt taggade.

För standarder som tillhandahåller en kodningstyp är en strukturliste något redundant. Den kan dock användas för att hjälpa en server att skicka rätt kodningshuvud. Alternativt kan den användas som reserv om kodningen annars går förlorad.

Det finns vissa nackdelar med att använda en strukturlista. Det kan till exempel vara svårt att veta hur databasfälten som använder en strukturlista ska begränsas. Sammanfogning av filer kan vara ett problem, till exempel när filer slås samman på ett sådant sätt att ett onödigt tecken kan hamna mitt i data. Trots de få nackdelarna rekommenderas dock användningen av en strukturlista starkt.

Important

För att säkerställa att de kodade byteen avkodas korrekt bör du prefixa början av en ström med kodade byte med en ingress. Observera att GetBytes metoden inte förbereder en bom till en sekvens med kodade byte. Det är utvecklarens ansvar att tillhandahålla en strukturlista i början av en lämplig byteström.