UTF32Encoding.GetPreamble Méthode

Référence

Définition

Espace de noms:: System.Text

Assemblys:: mscorlib.dll, System.Text.Encoding.Extensions.dll

Assembly:: System.Text.Encoding.Extensions.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Retourne une marque d'ordre d'octet Unicode encodée au format UTF-32 si l'objet UTF32Encoding est configuré pour en fournir une.

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

public override byte[] GetPreamble ();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Retours

Byte[]

Tableau d'octets contenant la marque d'ordre d'octet Unicode, si l'objet UTF32Encoding est configuré pour en fournir une. Sinon, cette méthode retourne un tableau d'octets de longueur égale à zéro.

Exemples

L’exemple de code suivant récupère et affiche la marque d’ordre d’octet pour différentes UTF32Encoding instances.

using namespace System;
using namespace System::Text;

void PrintHexBytes( array<Byte>^bytes );

int main()
{
   
   // Create instances of UTF32Encoding, with the byte order mark and without.
   UTF32Encoding ^ u32LeNone = gcnew UTF32Encoding;
   UTF32Encoding ^ u32BeNone = gcnew UTF32Encoding( true,false );
   UTF32Encoding ^ u32LeBom = gcnew UTF32Encoding( false,true );
   UTF32Encoding ^ u32BeBom = gcnew UTF32Encoding( true,true );
   
   // Display the preamble for each instance.
   PrintHexBytes( u32LeNone->GetPreamble() );
   PrintHexBytes( u32BeNone->GetPreamble() );
   PrintHexBytes( u32LeBom->GetPreamble() );
   PrintHexBytes( u32BeBom->GetPreamble() );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (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
*/

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

L’exemple suivant instancie deux UTF32Encoding objets, dont le premier ne fournit pas de marque d’ordre et le second. Il appelle ensuite la GetPreamble méthode pour écrire le boM dans un fichier avant d’écrire une chaîne encodée en UTF-32. Comme le montre la sortie de l’exemple, le fichier qui enregistre les octets du deuxième encodeur comporte quatre octets supplémentaires que le premier.

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.

Vous pouvez également comparer les fichiers à l’aide de la fc commande dans une fenêtre de console, ou inspecter les fichiers dans un éditeur de texte qui inclut un mode Affichage hexadécimal. Notez que lorsque le fichier est ouvert dans un éditeur qui prend en charge UTF-32, le boM n’est pas affiché.

Remarques

L’objet UTF32Encoding peut fournir un préambule, qui est un tableau d’octets qui peut être précédé de la séquence d’octets résultant du processus d’encodage. La précédation d’une séquence d’octets codés avec une marque d’ordre d’octet (points de code U+0000 U+FEFF) permet au décodeur de déterminer l’ordre d’octet et le format de transformation, ou UTF. La marque d’ordre d’octet Unicode (BOM) est sérialisée comme suit (au format hexadécimal) :

Ordre d’octet big endian : 00 00 FE FF
Petit ordre d’octet endian: FF FE 00 00

Vous pouvez instancier un UTF32Encoding objet dont GetPreamble la méthode retourne une marque d’ordre valide de la manière suivante :

En récupérant l’objet UTF32Encoding retourné par la Encoding.UTF32 propriété.
En appelant le constructeur sans UTF32Encoding() paramètre pour instancier un UTF32Encoding objet.
En fournissant true comme valeur de l’argument byteOrderMark aux UTF32Encoding constructeurs et UTF32Encoding aux constructeurs.

Nous vous recommandons d’utiliser le boM, car il fournit presque une certaine identification d’un encodage pour les fichiers qui ont autrement perdu la référence à l’objet UTF32Encoding , par exemple, des données web non étiquetées ou mal étiquetées, ou des fichiers texte aléatoires stockés lorsqu’une entreprise n’a pas de préoccupations internationales ou d’autres données. Souvent, les problèmes utilisateur peuvent être évités si les données sont étiquetées de manière cohérente et correctement.

Pour les normes qui fournissent un type d’encodage, une nomenclature est un peu redondante. Toutefois, il peut être utilisé pour aider un serveur à envoyer l’en-tête d’encodage correct. Vous pouvez également l’utiliser comme secours au cas où l’encodage serait perdu.

L’utilisation d’une nomenclature présente quelques inconvénients. Par exemple, il peut être difficile de savoir comment limiter les champs de base de données qui utilisent une nomenclature. La concaténation de fichiers peut également être un problème, par exemple, lorsque des fichiers sont fusionnés de manière à ce qu’un caractère inutile puisse se retrouver au milieu des données. Malgré les quelques inconvénients, toutefois, l’utilisation d’une nomenclature est fortement recommandée.

Pour plus d’informations sur l’ordre d’octet et la marque d’ordre d’octet, consultez la norme Unicode sur la page d’hébergement Unicode.