UTF8Encoding.GetPreamble Méthode

Référence

Définition

Espace de noms:: System.Text

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

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Source:: UTF8Encoding.cs

Source:: UTF8Encoding.cs

Source:: UTF8Encoding.cs

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 au format UTF-8, si l'objet de codage UTF8Encoding 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 de codage UTF8Encoding est configuré pour en fournir une. Sinon, cette méthode retourne un tableau d'octets de longueur égale à zéro.

Exemples

L’exemple suivant utilise la GetPreamble méthode pour renvoyer la marque d’ordre d’octet Unicode encodée au format UTF-8. Notez que le constructeur sans paramètre pour UTF8Encoding ne fournit pas de préambule.

using namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(array<Byte>^ bytes)
{
   for each (Byte b in bytes)
      Console::Write( "{0:X2} ", b);

   Console::WriteLine();
}

int main()
{
   // The default constructor does not provide a preamble.
   UTF8Encoding^ UTF8NoPreamble = gcnew UTF8Encoding;
   UTF8Encoding^ UTF8WithPreamble = gcnew UTF8Encoding( true );
   array<Byte>^preamble;
   preamble = UTF8NoPreamble->GetPreamble();
   Console::WriteLine( "UTF8NoPreamble" );
   Console::WriteLine( " preamble length: {0}", preamble->Length );
   Console::Write( " preamble: " );
   ShowArray( preamble );
   Console::WriteLine();
   
   preamble = UTF8WithPreamble->GetPreamble();
   Console::WriteLine( "UTF8WithPreamble" );
   Console::WriteLine( " preamble length: {0}", preamble->Length );
   Console::Write( " preamble: " );
   ShowArray( preamble );
}
// The example displays the following output:
//       UTF8NoPreamble
//        preamble length: 0
//        preamble:
//
//       UTF8WithPreamble
//        preamble length: 3
//        preamble: EF BB BF

using System;
using System.Text;

class Example
{
    public static void Main()
    {
        // The default constructor does not provide a preamble.
        UTF8Encoding UTF8NoPreamble = new UTF8Encoding();
        UTF8Encoding UTF8WithPreamble = new UTF8Encoding(true);

        Byte[] preamble;

        preamble = UTF8NoPreamble.GetPreamble();
        Console.WriteLine("UTF8NoPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
        Console.WriteLine();
        
        preamble = UTF8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
    }

    public static void ShowArray(Byte[] bytes)
    {
        foreach (var b in bytes)
            Console.Write("{0:X2} ", b);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    UTF8NoPreamble
//     preamble length: 0
//     preamble:
//
//    UTF8WithPreamble
//     preamble length: 3
//     preamble: EF BB BF

Imports System.Text

Module Example
    Public Sub Main()
        ' The default constructor does not provide a preamble.
        Dim UTF8NoPreamble As New UTF8Encoding()
        Dim UTF8WithPreamble As New UTF8Encoding(True)
        
        Dim preamble() As Byte
        
        preamble = UTF8NoPreamble.GetPreamble()
        Console.WriteLine("UTF8NoPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
        Console.WriteLine()
        
        preamble = UTF8WithPreamble.GetPreamble()
        Console.WriteLine("UTF8WithPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
    End Sub

    Public Sub ShowArray(bytes As Byte())
        For Each b In  bytes
            Console.Write("{0:X2} ", b)
        Next
        Console.WriteLine()
    End Sub
End Module
' The example displays the following output:
'    UTF8NoPreamble
'     preamble length: 0
'     preamble:
'
'    UTF8WithPreamble
'     preamble length: 3
'     preamble: EF BB BF

L’exemple suivant instancie deux UTF8Encoding objets, le premier en appelant le constructeur sans UTF8Encoding() paramètre, qui ne fournit pas de nomenclature, et le second en appelant le UTF8Encoding(Boolean) constructeur avec son encoderShouldEmitUTF8Identifier argument défini sur true. Il appelle ensuite la GetPreamble méthode pour écrire la nomenclature dans un fichier avant d’écrire une chaîne encodée en UF8. Comme le montre la sortie de console de l’exemple, le fichier qui enregistre les octets du deuxième encodeur a trois octets de 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-8 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF8Encoding();
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile("NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF8Encoding(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 57 bytes to NoPreamble.txt.
//
//       Preamble has 3 bytes
//       Wrote 60 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-8 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF8Encoding()
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF8Encoding(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 57 bytes to NoPreamble.txt.
'
'       Preamble has 3 bytes
'       Wrote 60 bytes to Preamble.txt.

Vous pouvez également comparer les fichiers à l’aide de la fc commande dans une fenêtre de console, ou vous pouvez 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-8, la nomenclature n’est pas affichée.

Remarques

L’objet UTF8Encoding peut fournir un préambule, qui est un tableau d’octets qui peut être préfixé à la séquence d’octets résultant du processus d’encodage. Le préfaçage d’une séquence d’octets codés avec une marque d’ordre d’octet (point de code U+FEFF) aide le décodeur à déterminer l’ordre d’octets et le format de transformation, ou UTF. La marque d’ordre d’octet Unicode est sérialisée en tant que 0xEF 0xBB 0xBF. Notez que la norme Unicode n’exige ni ne recommande l’utilisation d’une nomenclature pour les flux encodés en UTF-8.

Vous pouvez instancier un UTF8Encoding objet dont GetPreamble la méthode retourne une nomenclature valide des manières suivantes :

En récupérant l’objet UTF8Encoding retourné par la Encoding.UTF8 propriété .
En appelant un UTF8Encoding constructeur avec un encoderShouldEmitUTF8Identifier paramètre et en définissant sa valeur sur true.

Tous les autres UTF8Encoding objets sont configurés pour retourner un tableau vide plutôt qu’une nomenclature valide.

La nomenclature fournit presque une certaine identification d’un encodage pour les fichiers qui, autrement, ont perdu une référence à leur encodage, tels que des données web non marquées ou mal étiquetées ou des fichiers texte aléatoires stockés lorsqu’une entreprise n’avait pas de préoccupations internationales. Souvent, les problèmes des utilisateurs 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.

Important

Pour vous assurer que les octets encodés sont correctement décodés lorsqu’ils sont enregistrés en tant que fichier ou en tant que flux, vous pouvez préfixer le début d’un flux d’octets encodés d’un préambule. Notez que la GetBytes méthode n’ajoute pas une nomenclature à une séquence d’octets encodés ; la fourniture d’une nomenclature au début d’un flux d’octets approprié est la responsabilité du développeur.

S’applique à

Partage via