UTF8Encoding.GetPreamble Metod

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Returer

En bytematris som innehåller Unicode-byteordningsmarkeringen UTF8Encoding om kodningsobjektet har konfigurerats för att ange en. Annars returnerar den här metoden en bytematris med noll längd.

Exempel

I följande exempel används GetPreamble metoden för att returnera Unicode-byteordningsmärket som är kodat i UTF-8-format. Observera att den parameterlösa konstruktorn för UTF8Encoding inte tillhandahåller någon ingress.

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

I följande exempel instansierar två UTF8Encoding objekt, det första genom att anropa den parameterlösa UTF8Encoding() konstruktorn, som inte tillhandahåller en bom, och det andra genom att anropa UTF8Encoding(Boolean) konstruktorn med argumentet encoderShouldEmitUTF8Identifier inställt på true. Sedan anropas GetPreamble metoden för att skriva bommen till en fil innan du skriver en UF8-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-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.

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-8 visas inte strukturlistan.

Kommentarer

Objektet UTF8Encoding kan ange en ingress, vilket ä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 som 0xEF 0xBB 0xBF. Observera att Unicode Standard varken kräver eller rekommenderar användning av en BOM för UTF-8-kodade strömmar.

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

• Genom att hämta objektet UTF8Encoding som returneras av Encoding.UTF8 egenskapen.

• Genom att anropa en UTF8Encoding konstruktor med en encoderShouldEmitUTF8Identifier parameter och ange dess värde till true.

Alla andra UTF8Encoding objekt är konfigurerade för att returnera en tom matris i stället för en giltig strukturlista.

Bommen ger nästan säker 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.

Mer information om byteordning och byteordningsmarkering finns i Unicode Standard på Unicode-startsidan.