Base64 em C#: codificação e decodificação de strings com exemplos

Base64 em C#: como codificar e decodificar strings sem dor de cabeça

Você já se deparou com uma situação em que precisa transmitir dados binários através de um protocolo de texto, enviar uma imagem em JSON ou salvar um hash em formato legível? É aqui que entra o Base64 — o velho, bom e confiável formato que transforma qualquer byte em texto seguro.

A pergunta "How do I encode and decode a base64 string?" é uma das mais populares no Stack Overflow (dezenas de milhares de visualizações). E não é à toa: em C#, trabalhar com Base64 parece simples, mas as armadilhas aparecem a cada passo. Hoje vamos abordar tudo do início ao fim: desde exemplos básicos até casos reais de produção.

O que é Base64 e para que serve?

Base64 é uma forma de representar dados binários (bytes) como uma string ASCII. O alfabeto consiste em 64 caracteres: A-Z, a-z, 0-9, além dos caracteres '+' e '/'. No final da string, frequentemente é adicionado o caractere '=' para alinhamento.

Onde é aplicado:

\n
• Transmissão de dados em JSON/XML — dados binários não podem ser inseridos diretamente, apenas como string
\n
• Autenticação — Basic Auth usa Base64 para codificar login e senha
\n
• Armazenamento de imagens em BD — imagens pequenas são armazenadas diretamente no banco como Base64
\n
• Anexos de e-mail — o formato MIME exige Base64 para arquivos binários
\n

Em C#, tudo isso é tratado pela classe System.Convert — sua principal ferramenta para trabalhar com Base64.

Como codificar uma string em Base64 em C#

O cenário mais comum: você tem uma string comum (por exemplo, "Olá, mundo!") e deseja obter sua representação em Base64.

Veja como fazer:

using System;\nusing System.Text;\n\nstring original = "Hello, World!";\nbyte[] bytes = Encoding.UTF8.GetBytes(original);\nstring base64 = Convert.ToBase64String(bytes);\n\nConsole.WriteLine(base64); // Saída: SGVsbG8sIFdvcmxkIQ==

Ponto importante: Base64 trabalha com bytes, não com strings. Portanto, primeiro convertemos a string em um array de bytes (usando a codificação UTF-8) e depois codificamos esses bytes.

Por que UTF-8 e não, por exemplo, ASCII? Porque UTF-8 suporta todos os caracteres Unicode, incluindo cirílico, ideogramas e emojis. Se você usar ASCII para strings em russo, os dados serão perdidos.

Como decodificar Base64 de volta para string

O processo inverso — decodificação — é espelhado:

using System;\nusing System.Text;\n\nstring base64 = "SGVsbG8sIFdvcmxkIQ==";\nbyte[] bytes = Convert.FromBase64String(base64);\nstring decoded = Encoding.UTF8.GetString(bytes);\n\nConsole.WriteLine(decoded); // Saída: Hello, World!

Observe: se você codificou a string em UTF-8, também deve decodificá-la em UTF-8. Caso contrário, obterá caracteres ilegíveis.

Trabalhando com dados binários (imagens, arquivos)

Base64 não se limita a strings. Você pode codificar qualquer dado binário — por exemplo, uma imagem ou PDF.

Exemplo: codificando um array de bytes em Base64

byte[] imageBytes = File.ReadAllBytes("photo.jpg");\nstring base64Image = Convert.ToBase64String(imageBytes);\n\n// Agora você pode salvar a string em JSON ou enviar via API\nConsole.WriteLine($"Tamanho da string Base64: {base64Image.Length} caracteres");

Decodificando de volta para arquivo:

string base64Image = "..."; // sua string\nbyte[] imageBytes = Convert.FromBase64String(base64Image);\nFile.WriteAllBytes("decoded_photo.jpg", imageBytes);

Importante: Base64 aumenta o tamanho dos dados em aproximadamente 33%. Se você tem uma imagem de 1 MB, após a codificação ela pesará ~1.33 MB como string.

Erros típicos e como evitá-los

Mesmo desenvolvedores experientes às vezes tropeçam no Base64. Aqui estão os erros mais comuns: