1. Introdução
Dicionário (ou Dictionary<TKey, TValue> em C#) — é uma coleção de pares "chave-valor". Esse tipo de dado é indispensável quando você precisa encontrar rapidamente um valor por um identificador único (por exemplo, procurar um telefone pelo nome na agenda).
Ao contrário de listas (List<T>), onde a ordem dos elementos importa, o dicionário foca no acesso rápido por chave. Mas se ao serializar uma lista tudo é simples (um array JSON), ao serializar um dicionário surgem vários detalhes:
- A chave precisa ser de um tipo serializável (na maioria das vezes string, mas às vezes pode ser um número ou até outro objeto).
- No JSON não existem dicionários separados — só objetos ou arrays.
Vamos ver em detalhes como o .NET serializa dicionários, quais dificuldades podem aparecer e como "ensinar" corretamente nosso código a trabalhar com essas estruturas.
2. Serialização de dicionário com chaves-string
Começamos pelo clássico — dicionário onde tanto a chave quanto o valor são strings.
// Exemplo de dicionário: livro e seu autor
var books = new Dictionary<string, string>
{
["Master i Margarita"] = "Mikhail Bulgakov",
["Garri Potter"] = "Joan Rowling",
["Povelitel mukh"] = "William Golding"
};
// Serialização para string JSON
string json = JsonSerializer.Serialize(books, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine("Dicionário serializado em JSON:\n" + json);
// Salvar em arquivo (síncrono)
File.WriteAllText("books.json", json);
Console.WriteLine("JSON gravado no arquivo books.json.");
// Ler de volta do arquivo (síncrono)
string jsonFromFile = File.ReadAllText("books.json");
// Desserialização de volta ao dicionário
var restoredBooks = JsonSerializer.Deserialize<Dictionary<string, string>>(jsonFromFile);
Console.WriteLine("Resultado da desserialização:");
foreach (var pair in restoredBooks)
Console.WriteLine($"{pair.Key} -> {pair.Value}");
O que vai ficar no arquivo books.json?
{
"Master i Margarita": "Mikhail Bulgakov",
"Garri Potter": "Joan Rowling",
"Voyna i mir": "William Golding"
}
Como isso funciona?
O serializador transforma nosso Dictionary<string, string> em um objeto JSON, onde cada chave vira um nome de propriedade e o valor vira o valor da propriedade. Isso é conveniente quando as chaves são strings e únicas.
3. Dicionário com tipo de chave não padrão
Tudo é simples enquanto a chave for string. E se for, por exemplo, um número?
var bookIds = new Dictionary<int, string>
{
[1001] = "Master i Margarita",
[1002] = "Garri Potter",
[1003] = "Povelitel mukh"
};
string jsonIntKeys = JsonSerializer.Serialize(bookIds, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(jsonIntKeys);
Resultado:
{
"1001": "Master i Margarita",
"1002": "Garri Potter",
"1003": "Povelitel mukh"
}
O que aconteceu?
- O C# converteu as chaves numéricas em strings, porque em JSON nomes de propriedades só podem ser strings.
- Ao desserializar de volta para Dictionary<int, string> o serializador tentará converter de volta a string para número.
Exemplo de desserialização:
var restoredBookIds = JsonSerializer.Deserialize<Dictionary<int, string>>(jsonIntKeys);
// Tudo funciona! As chaves voltaram a ser números.
E se a chave for um tipo complexo, por exemplo, um objeto?
var dict = new Dictionary<Author, string>
{
[new Author { Name = "Golding", BirthYear = 1911 }] = "Povelitel mukh"
};
Tentar serializar esse dicionário vai gerar uma exceção:
System.NotSupportedException: Serialization and deserialization of 'Dictionary<Author, string>' instances are not supported.
Por que isso?
Um objeto JSON não pode usar nada além de string como nome de propriedade. Logo, chaves de dicionário na serialização devem ser tipos simples, que se convertem de forma única para string (normalmente string ou número). Objetos complexos não podem ser usados como chaves quando se serializa para JSON com as ferramentas padrão.
4. Dicionário com objetos aninhados como valor
As chaves já estão explicadas — agora vamos ver o que acontece se o valor for um objeto complexo (por exemplo, Book ou Author).
Exemplo
public class Author
{
public string Name { get; set; }
public int BirthYear { get; set; }
}
var authorDirectory = new Dictionary<string, Author>
{
["bulgakov"] = new Author { Name = "Mikhail Bulgakov", BirthYear = 1891 },
["golding"] = new Author { Name = "William Golding", BirthYear = 1911 }
};
string jsonAuthors = JsonSerializer.Serialize(authorDirectory, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(jsonAuthors);
Resultado:
{
"bulgakov": {
"Name": "Mikhail Bulgakov",
"BirthYear": 1891
},
"golding": {
"Name": "William Golding",
"BirthYear": 1911
}
}
- Tudo que estiver aninhado é serializado conforme a estrutura dos objetos.
- A desserialização de volta para Dictionary<string, Author> também funciona normalmente.
5. Dicionário como parte de outro objeto
Muito frequentemente dicionários são usados como campos dentro de um objeto maior. Por exemplo, uma biblioteca pode ter um catálogo onde cada chave é o nome do gênero e o valor é a lista de livros desse gênero.
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
public class Library
{
public Dictionary<string, List<Book>> CatalogByGenre { get; set; }
}
var library = new Library
{
CatalogByGenre = new Dictionary<string, List<Book>>
{
["F fantastika"] = new List<Book>
{
new Book { Title = "Solaris", Author = "Stanislaw Lem" }
},
["K klassika"] = new List<Book>
{
new Book { Title = "Povelitel mukh", Author = "William Golding" },
new Book { Title = "Zrimaya tma", Author = "William Golding" }
}
}
};
string jsonLibrary = JsonSerializer.Serialize(library, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(jsonLibrary);
Trecho do JSON de saída:
{
"CatalogByGenre": {
"F fantastika": [
{
"Title": "Solaris",
"Author": "Stanislaw Lem"
}
],
"K klassika": [
{
"Title": "Povelitel mukh",
"Author": "William Golding"
},
{
"Title": "Zrimaya tma",
"Author": "William Golding"
}
]
}
}
Tudo funciona — dicionários e coleções aninhadas são serializados e desserializados recursivamente.
6. Particularidades e "armadilhas" da serialização de dicionários
Chaves duplicadas
Em um dicionário as chaves são sempre únicas. Mas se você colocar manualmente um JSON com chaves duplicadas:
{
"foo": "first",
"foo": "second"
}
Resultado: o último valor ("second") sobrescreve o primeiro, não ocorre erro. Assim funcionam a maioria dos parsers JSON.
Ordem dos elementos
Dicionário é uma coleção não ordenada. Ao serializar a ordem das chaves no JSON pode diferir da original. Se a ordem for crítica — use uma lista de pares (List<KeyValuePair<string, T>>), mas normalmente em dicionário a ordem não importa.
JSON e dicionários aninhados
Os níveis de aninhamento não têm limite, mas para funcionar corretamente cada nível deve obedecer às regras do JSON (chaves — strings, valores — objetos/arrays JSON válidos).
Uso de JsonSerializerOptions
Às vezes é preciso que os nomes das propriedades não fiquem em PascalCase, e sim em camelCase. Isso é especialmente importante se você integra com frontend em JavaScript, onde camelCase costuma ser o padrão dos campos.
var options = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
WriteIndented = true
};
string camelJson = JsonSerializer.Serialize(authorDirectory, options);
Importante: em dicionários essa opção afeta somente a serialização dos objetos aninhados (suas propriedades), e não as chaves do dicionário. As chaves do dicionário sempre são serializadas exatamente como a string que estava no C#.
7. Problemas com chaves complexas e não-string
Com dicionários de chaves-string e chaves numéricas (por exemplo, int, long, Guid) tudo funciona "fora da caixa". Mas se você tentar usar uma classe customizada ou struct como chave — receberá uma NotSupportedException.
Existem abordagens para contornar esses casos:
- Usar outro formato de armazenamento, por exemplo, serializar o dicionário como um array de objetos com campos "Key" e "Value".
- Escrever um conversor (JsonConverter) que converta sua chave complexa para string e de volta.
- Se a estrutura for realmente complexa — às vezes vale repensar a arquitetura e não usar objetos complexos como chave do dicionário.
Exemplo de workaround serializando como lista de pares
public class AuthorInfo
{
public Author Author { get; set; }
public string Book { get; set; }
}
// em vez de Dictionary<Author, string>
var list = new List<AuthorInfo>
{
new AuthorInfo { Author = new Author { Name = "William Golding", BirthYear = 1911 }, Book = "Povelitel mukh" }
};
// essa lista serializa sem problemas
Comparação: dicionário vs lista de pares na serialização
| Tipo de coleção | Estrutura JSON | Quando usar |
|---|---|---|
|
|
Chaves — strings simples, precisa de busca rápida e unicidade |
|
|
Chave é tipo complexo, precisa controlar ordem, duplicatas possíveis |
8. Perguntas típicas em entrevistas
1. Dá para serializar Dictionary<DateTime, string>?
Sim, mas as chaves são convertidas para representação string (geralmente no formato ISO tipo "yyyy-MM-ddTHH:mm:ss"). Às vezes, na desserialização, podem surgir problemas com locales e formatos de data.
2. O que acontece se serializar Dictionary<int, string>?
As chaves serão serializadas como strings, mesmo que no dicionário original fossem números. Na desserialização voltam ao tipo numérico corretamente.
3. Por que não é possível serializar um dicionário com objetos como chave?
Porque somente strings podem ser nomes de propriedades de um objeto JSON, objetos não podem.
4. E se eu quiser serializar um dicionário com chave complexa?
Melhor repensar a estrutura ou serializar como uma lista de pares "key-value", onde a chave é serializada integralmente como um objeto-campo, não como nome de propriedade.
GO TO FULL VERSION