UTF32Encoding.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 UTF32Encoding om objektet är konfigurerat att ange en. Annars returnerar den här metoden en bytematris med noll längd.

Exempel

Följande kodexempel hämtar och visar byteordningsmarkeringen för olika UTF32Encoding instanser.

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

I följande exempel instansieras två UTF32Encoding 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 UTF-32-kodad sträng. Som utdata från exemplet visar har filen som sparar byte från den andra kodaren ytterligare fyra byte som 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-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.

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

Kommentarer

Objektet UTF32Encoding kan ange en ingress, som är en matris med byte 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 (kodpunkter U+0000 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: 00 00 FE FF

• Lite endiansk byteordning: FF FE 00 00

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

• Genom att hämta objektet UTF32Encoding som returneras av Encoding.UTF32 egenskapen.

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

• Genom att true ange som värdet för byteOrderMark argumentet till konstruktorerna UTF32Encoding och UTF32Encoding .

Vi rekommenderar att du använder strukturlistan eftersom den ger nästan viss identifiering av en kodning för filer som annars har förlorat referensen UTF32Encoding till objektet, till exempel otaggade eller felaktigt taggade webbdata eller slumpmässiga textfiler som lagras när ett företag inte har internationella problem eller andra data. 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.