UnicodeEncoding.GetPreamble Méthode

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 UnicodeEncoding est configuré pour en fournir une. Sinon, cette méthode retourne un tableau d'octets de longueur égale à zéro.

Exemples

L’exemple suivant montre comment utiliser la GetPreamble méthode pour récupérer la marque d’ordre d’octet Unicode dans l’ordre d’octet big endian ou little endian pour une instance d’un UnicodeEncoding.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^byteOrderMark;
   byteOrderMark = Encoding::Unicode->GetPreamble();
   Console::WriteLine( "Default (little-endian) Unicode Preamble:" );
   IEnumerator^ myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine( "\n" );
   UnicodeEncoding^ bigEndianUnicode = gcnew UnicodeEncoding( true,true );
   byteOrderMark = bigEndianUnicode->GetPreamble();
   Console::WriteLine( "Big-endian Unicode Preamble:" );
   myEnum = byteOrderMark->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }
}

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

L’exemple suivant instancie deux UnicodeEncoding objets, dont le premier ne fournit pas de boM, et le second le fait. Il appelle ensuite la GetPreamble méthode pour écrire le boM dans un fichier avant d’écrire une chaîne encodée Unicode. Comme le montre la sortie de la console de l’exemple, le fichier qui enregistre les octets du deuxième encodeur comporte trois octets plus 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-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.

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 l’encodage UTF-16, le boM n’est pas affiché.

Remarques

L’objet UnicodeEncoding 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 (point de code 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 : FE FF

• Ordre d’octets little endian: FF FE

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

• En récupérant l’objet UnicodeEncoding retourné par la ou Encoding.BigEndianUnicode la Encoding.Unicode propriété.

• En appelant le constructeur sans UnicodeEncoding() paramètre pour instancier un UnicodeEncoding objet.

• En fournissant true comme valeur de l’argument byteOrderMark aux UnicodeEncoding(Boolean, Boolean) constructeurs ou UnicodeEncoding(Boolean, Boolean, Boolean) 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 une référence à leur encodage, comme les données web non étiquetées ou mal étiquetées ou les fichiers texte aléatoires stockés lorsqu’une entreprise n’a pas de préoccupations internationales. Souvent, les problèmes utilisateur peuvent être évités si les données sont marquées de manière cohérente et correctement marquées.

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.

S’applique à