UTF8Encoding.GetPreamble Methode

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Retouren

Een bytematrix met de Unicode-bytevolgordemarkering, als het UTF8Encoding coderingsobject is geconfigureerd om er een op te geven. Anders retourneert deze methode een bytematrix met lengte nul.

Voorbeelden

In het volgende voorbeeld wordt de GetPreamble methode gebruikt om het Unicode byte ordermarkering te retourneren dat is gecodeerd in UTF-8-indeling. U ziet dat de parameterloze constructor voor UTF8Encoding geen preparameter een preparate bevat.

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

In het volgende voorbeeld worden twee UTF8Encoding objecten geïnstitueerd, de eerste door het aanroepen van de parameterloze UTF8Encoding() constructor, die geen stuklijst biedt en de tweede door de UTF8Encoding(Boolean) constructor aan te roepen met het encoderShouldEmitUTF8Identifier bijbehorende argument ingesteld op true. Vervolgens wordt de GetPreamble methode aangeroepen om de BOM naar een bestand te schrijven voordat u een UF8-gecodeerde tekenreeks schrijft. Zoals de console-uitvoer uit het voorbeeld laat zien, heeft het bestand dat de bytes van de tweede encoder opslaat drie meer bytes dan de eerste.

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.

U kunt de bestanden ook vergelijken met behulp van de fc opdracht in een consolevenster of u kunt de bestanden controleren in een teksteditor die een Hex-weergavemodus bevat. Houd er rekening mee dat wanneer het bestand wordt geopend in een editor die UTF-8 ondersteunt, de BOM niet wordt weergegeven.

Opmerkingen

Het UTF8Encoding object kan een preambule bieden, een bytematrix die kan worden voorafgegaan door de reeks bytes die het gevolg zijn van het coderingsproces. Door een reeks gecodeerde bytes vooraf te laten gaan met een bytevolgordemarkering (codepunt U+FEFF) kan de decoder de bytevolgorde en de transformatie-indeling of UTF bepalen. De Unicode byte order mark (BOM) wordt geserialiseerd als 0xEF 0xBB 0xBF. Houd er rekening mee dat de Unicode-standaard het gebruik van een BOM voor UTF-8 gecodeerde streams niet vereist of aanbeveelt.

U kunt op de volgende manieren een UTF8Encoding object instantiëren waarvan GetPreamble de methode een geldige stuklijst retourneert:

• Door het UTF8Encoding object op te halen dat door de Encoding.UTF8 eigenschap wordt geretourneerd.

• Door een UTF8Encoding constructor aan te roepen met een encoderShouldEmitUTF8Identifier parameter en de waarde ervan in te truestellen op .

Alle andere UTF8Encoding objecten zijn geconfigureerd om een lege matrix te retourneren in plaats van een geldige stuklijst.

De BOM biedt vrijwel bepaalde identificatie van een codering voor bestanden die anders een verwijzing naar hun codering hebben verloren, zoals niet-gemarkeerde of onjuist gelabelde webgegevens of willekeurige tekstbestanden die zijn opgeslagen wanneer een bedrijf geen internationale zorgen had. Vaak worden gebruikersproblemen vermeden als gegevens consistent en correct zijn gelabeld.

Voor standaarden die een coderingstype bieden, is een stuklijst enigszins redundant. Het kan echter worden gebruikt om een server te helpen de juiste coderingsheader te verzenden. Het kan ook worden gebruikt als een terugval in het geval dat de codering anders verloren gaat.

Er zijn enkele nadelen voor het gebruik van een BOM. Het kan bijvoorbeeld lastig zijn om te weten hoe u de databasevelden kunt beperken die gebruikmaken van een stuklijst. Samenvoeging van bestanden kan ook een probleem zijn, bijvoorbeeld wanneer bestanden zo worden samengevoegd dat een onnodig teken midden in de gegevens terecht kan komen. Ondanks de weinige nadelen wordt het gebruik van een BOM echter ten zeerste aanbevolen.

Voor meer informatie over bytevolgorde en het byte-ordemerk, zie de Unicode-standaard op de Unicode-startpagina.