UnicodeEncoding.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 UnicodeEncoding object is geconfigureerd om er een op te geven. Anders retourneert deze methode een bytematrix met lengte nul.

Voorbeelden

In het volgende voorbeeld ziet u hoe u de GetPreamble methode gebruikt om het Unicode-bytevolgordeteken op te halen in big endian of little endian bytevolgorde voor een exemplaar van een 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

In het volgende voorbeeld worden twee UnicodeEncoding objecten geïnstitueert, waarvan de eerste geen stuklijst bevat en waarvan de tweede wel. Vervolgens wordt de GetPreamble methode aangeroepen om de BOM naar een bestand te schrijven voordat een Unicode-gecodeerde tekenreeks wordt geschreven. 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-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.

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-16-codering ondersteunt, de bom niet wordt weergegeven.

Opmerkingen

Het UnicodeEncoding 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 als volgt geserialiseerd (in hexadecimaal):

• Big endian byte order: FE FF

• Little endian byte order: FF FE

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

• Door het UnicodeEncoding object op te halen dat wordt geretourneerd door de Encoding.Unicode of Encoding.BigEndianUnicode eigenschap.

• Door de parameterloze UnicodeEncoding() constructor aan te roepen om een UnicodeEncoding object te instantiëren.

• Door op te geven true als de waarde van het byteOrderMark argument aan de UnicodeEncoding(Boolean, Boolean) of UnicodeEncoding(Boolean, Boolean, Boolean) constructors.

We raden u aan de bom te gebruiken, omdat het bijna bepaalde identificatie biedt 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.