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

Voorbeelden

In het volgende codevoorbeeld wordt de bytevolgordemarkering voor verschillende UTF32Encoding exemplaren opgehaald en weergegeven.

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   Public Shared Sub PrintHexBytes(bytes() As Byte)
      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else
         Dim i As Integer
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If
   End Sub
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

In het volgende voorbeeld worden twee UTF32Encoding 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 u een UTF-32-gecodeerde tekenreeks schrijft. Zoals de uitvoer uit het voorbeeld laat zien, heeft het bestand dat de bytes van de tweede encoder opslaat nog vier bytes die het eerste zijn.

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-32 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF32Encoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF32Encoding(! 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 232 bytes to .\NoPreamble.txt.
//
//       Preamble has 4 bytes
//       Wrote 236 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-32 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF32Encoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF32Encoding(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 232 bytes to NoPreamble.txt.
'
'       Preamble has 4 bytes
'       Wrote 236 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-32 ondersteunt, de BOM niet wordt weergegeven.

Opmerkingen

Het UTF32Encoding object kan een preambule bieden, een matrix van bytes die kunnen 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 (codepunten U+0000 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: 00 00 FE FF

• Little endian byte order: FF FE 00 00

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

• Door het UTF32Encoding object op te halen dat door de Encoding.UTF32 eigenschap wordt geretourneerd.

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

• Door op te geven true als de waarde van het byteOrderMark argument aan de UTF32Encoding en UTF32Encoding constructors.

We raden u aan de bom te gebruiken, omdat deze bijna bepaalde identificatie biedt van een codering voor bestanden die anders zijn verloren gegaan naar het UTF32Encoding object, bijvoorbeeld niet-gemarkeerde of onjuist gelabelde webgegevens, of willekeurige tekstbestanden die zijn opgeslagen wanneer een bedrijf geen internationale problemen of andere gegevens heeft. Gebruikersproblemen kunnen vaak worden 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.