UTF8Encoding Classe

Definição

public ref class UTF8Encoding : System::Text::Encoding

public class UTF8Encoding : System.Text.Encoding

[System.Serializable]
public class UTF8Encoding : System.Text.Encoding

[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class UTF8Encoding : System.Text.Encoding

type UTF8Encoding = class
    inherit Encoding

[<System.Serializable>]
type UTF8Encoding = class
    inherit Encoding

[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type UTF8Encoding = class
    inherit Encoding

Public Class UTF8Encoding
Inherits Encoding

Herança

Object

Encoding

UTF8Encoding

Atributos

SerializableAttribute ComVisibleAttribute

Exemplos

O exemplo a seguir usa um UTF8Encoding objeto para codificar uma cadeia de caracteres Unicode e armazená-los em uma matriz de bytes. A cadeia de caracteres Unicode inclui dois caracteres, Pi (U+03A0) e Sigma (U+03A3), que estão fora do intervalo de caracteres ASCII. Quando a matriz de bytes codificada é decodificada de volta para uma cadeia de caracteres, os caracteres Pi e Sigma ainda estão presentes.

using System;
using System.Text;

class Example
{
    public static void Main()
    {
        // Create a UTF-8 encoding.
        UTF8Encoding utf8 = new UTF8Encoding();
        
        // A Unicode string with two characters outside an 8-bit code range.
        String unicodeString =
            "This Unicode string has 2 characters outside the " +
            "ASCII range:\n" +
            "Pi (\u03a0), and Sigma (\u03a3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);

        // Encode the string.
        Byte[] encodedBytes = utf8.GetBytes(unicodeString);
        Console.WriteLine();
        Console.WriteLine("Encoded bytes:");
        for (int ctr = 0; ctr < encodedBytes.Length; ctr++) {
            Console.Write("{0:X2} ", encodedBytes[ctr]);
            if ((ctr + 1) %  25 == 0)
               Console.WriteLine();
        }
        Console.WriteLine();
        
        // Decode bytes back to string.
        String decodedString = utf8.GetString(encodedBytes);
        Console.WriteLine();
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
    }
}
// The example displays the following output:
//    Original string:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    Encoded bytes:
//    54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
//    20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
//    53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
//    64 20 53 69 67 6D 61 20 28 CE A3 29 2E
//
//    Decoded bytes:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).

Imports System.Text

Class Example
    Public Shared Sub Main()
        ' Create a UTF-8 encoding.
        Dim utf8 As New UTF8Encoding()
        
        ' A Unicode string with two characters outside an 8-bit code range.
        Dim unicodeString As String = _
            "This Unicode string has 2 characters outside the " &
            "ASCII range: " & vbCrLf &
            "Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        
        ' Encode the string.
        Dim encodedBytes As Byte() = utf8.GetBytes(unicodeString)
        Console.WriteLine()
        Console.WriteLine("Encoded bytes:")
        For ctr As Integer = 0 To encodedBytes.Length - 1
            Console.Write("{0:X2} ", encodedBytes(ctr))
            If (ctr + 1) Mod 25 = 0 Then Console.WriteLine
        Next
        Console.WriteLine()
        
        ' Decode bytes back to string.
        Dim decodedString As String = utf8.GetString(encodedBytes)
        Console.WriteLine()
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class
' The example displays the following output:
'    Original string:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    Encoded bytes:
'    54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
'    20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
'    53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
'    64 20 53 69 67 6D 61 20 28 CE A3 29 2E
'
'    Decoded bytes:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).

O exemplo a seguir usa a mesma cadeia de caracteres que o exemplo anterior, exceto que ele grava os bytes codificados em um arquivo e prefixa o fluxo de bytes com uma marca de ordem de byte (BOM). Em seguida, ele lê o arquivo de duas maneiras diferentes: como um arquivo de texto usando um StreamReader objeto; e como um arquivo binário. Como seria de esperar, nenhuma cadeia de caracteres recém-lida inclui o BOM.

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
        // Create a UTF-8 encoding that supports a BOM.
        Encoding utf8 = new UTF8Encoding(true);

        // A Unicode string with two characters outside an 8-bit code range.
        String unicodeString =
            "This Unicode string has 2 characters outside the " +
            "ASCII range:\n" +
            "Pi (\u03A0)), and Sigma (\u03A3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);
        Console.WriteLine();

        // Encode the string.
        Byte[] encodedBytes = utf8.GetBytes(unicodeString);
        Console.WriteLine("The encoded string has {0} bytes.",
                          encodedBytes.Length);
        Console.WriteLine();

        // Write the bytes to a file with a BOM.
        var fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Create);
        Byte[] bom = utf8.GetPreamble();
        fs.Write(bom, 0, bom.Length);
        fs.Write(encodedBytes, 0, encodedBytes.Length);
        Console.WriteLine("Wrote {0} bytes to the file.", fs.Length);
        fs.Close();
        Console.WriteLine();

        // Open the file using StreamReader.
        var sr = new StreamReader(@".\UTF8Encoding.txt");
        String newString = sr.ReadToEnd();
        sr.Close();
        Console.WriteLine("String read using StreamReader:");
        Console.WriteLine(newString);
        Console.WriteLine();

        // Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Open);
        Byte[] bytes = new Byte[fs.Length];
        fs.Read(bytes, 0, (int)fs.Length);
        fs.Close();

        String decodedString = utf8.GetString(bytes);
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
   }
}
// The example displays the following output:
//    Original string:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    The encoded string has 88 bytes.
//
//    Wrote 91 bytes to the file.
//
//    String read using StreamReader:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    Decoded bytes:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).

Imports System.IO
Imports System.Text

Class Example
    Public Shared Sub Main()
        ' Create a UTF-8 encoding that supports a BOM.
        Dim utf8 As New UTF8Encoding(True)
        
        ' A Unicode string with two characters outside an 8-bit code range.
        Dim unicodeString As String = _
            "This Unicode string has 2 characters outside the " &
            "ASCII range: " & vbCrLf &
            "Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        Console.WriteLine()
        
        ' Encode the string.
        Dim encodedBytes As Byte() = utf8.GetBytes(unicodeString)
        Console.WriteLine("The encoded string has {0} bytes.",
                          encodedBytes.Length)
        Console.WriteLine()
        
        ' Write the bytes to a file with a BOM.
        Dim fs As New FileStream(".\UTF8Encoding.txt", FileMode.Create)
        Dim bom() As Byte = utf8.GetPreamble()
        fs.Write(bom, 0, bom.Length)
        fs.Write(encodedBytes, 0, encodedBytes.Length)
        Console.WriteLine("Wrote {0} bytes to the file.", fs.Length)
        fs.Close()
        Console.WriteLine()
        
        ' Open the file using StreamReader.
        Dim sr As New StreamReader(".\UTF8Encoding.txt")
        Dim newString As String = sr.ReadToEnd()
        sr.Close()
        Console.WriteLine("String read using StreamReader:")
        Console.WriteLine(newString)
        Console.WriteLine()
        
        ' Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(".\UTF8Encoding.txt", FileMode.Open)
        Dim bytes(fs.Length - 1) As Byte
        fs.Read(bytes, 0, fs.Length)
        fs.Close()

        Dim decodedString As String = utf8.GetString(bytes)
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class
' The example displays the following output:
'    Original string:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    The encoded string has 88 bytes.
'
'    Wrote 91 bytes to the file.
'
'    String read using StreamReader:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    Decoded bytes:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).

Comentários

A codificação é o processo de transformação de um conjunto de caracteres Unicode em uma sequência de bytes. A decodificação é o processo de transformar uma sequência de bytes codificados em um conjunto de caracteres Unicode.

UTF-8 é uma codificação Unicode que representa cada ponto de código como uma sequência de um a quatro bytes. Ao contrário das codificações UTF-16 e UTF-32, a codificação UTF-8 não requer "endianidade"; o esquema de codificação é o mesmo, independentemente de o processador ser big-endian ou little-endian. UTF8Encoding corresponde à página de código do Windows 65001. Para obter mais informações sobre os UTFs e outras codificações com suporte System.Text, consulte Codificação de Caracteres no .NET Framework.

Você pode criar uma instância de um UTF8Encoding objeto de várias maneiras, dependendo se deseja fornecer uma BOM (marca de ordem de byte) e se deseja habilitar a detecção de erros. A tabela a seguir lista os construtores e a Encoding propriedade que retornam um UTF8Encoding objeto.

O GetByteCount método determina quantos bytes resultam na codificação de um conjunto de caracteres Unicode e o GetBytes método executa a codificação real.

Da mesma forma, o GetCharCount método determina quantos caracteres resultam na decodificação de uma sequência de bytes e os GetChars métodos e GetString executam a decodificação real.

Para um codificador ou decodificador que é capaz de salvar informações de estado ao codificar ou decodificar dados que abrangem vários blocos (como cadeia de caracteres de 1 milhão de caracteres que é codificada em segmentos de 100.000 caracteres), use o e GetDecoder as GetEncoder propriedades, respectivamente.

Opcionalmente, o UTF8Encoding objeto fornece uma marca de ordem de bytes (BOM), que é uma matriz de bytes que pode ser prefixada no início do fluxo de bytes resultante do processo de codificação. Se um fluxo de bytes codificado em UTF-8 for precedido por uma marca de ordem de bytes (BOM), ele ajudará o decodificador a determinar a ordem de bytes e o formato de transformação ou UTF. No entanto, observe que o Padrão Unicode não requer nem recomenda um BOM em fluxos codificados em UTF-8. Para obter mais informações sobre a ordem de bytes e a marca de ordem de bytes, consulte o Padrão Unicode na home page unicode.

Se o codificador estiver configurado para fornecer um BOM, você poderá recuperá-lo chamando o GetPreamble método; caso contrário, o método retornará uma matriz vazia. Observe que, mesmo que um UTF8Encoding objeto esteja configurado para suporte a BOM, você deve incluir o BOM no início do fluxo de bytes codificado conforme apropriado; os métodos de codificação da UTF8Encoding classe não fazem isso automaticamente.

Confira também

• Decoder
• Encoder
• Noções básicas sobre codificações