BinaryFormatter guia de migração

2025-06-18

Cuidado

É altamente recomendável não usar BinaryFormatter devido aos riscos de segurança associados. Os usuários existentes devem migrar do BinaryFormatter.

A partir do .NET 9, não incluímos mais uma implementação BinaryFormatter no runtime. As APIs ainda estão presentes, mas sua implementação sempre lança uma PlatformNotSupportedException, independentemente do tipo de projeto. Portanto, definir o sinalizador de compatibilidade com versões anteriores existentes não é mais suficiente para usar BinaryFormatter.

Você tem duas opções para resolver isso:

Migrar para longe de BinaryFormatter. Recomendamos que você investigue as opções para parar de usar BinaryFormatter devido aos riscos de segurança associados. Listamos várias opções abaixo.
Continue usando BinaryFormatter. Se você precisar continuar usando o BinaryFormatter no .NET 9, precisará depender do pacote NuGet System.Runtime.Serialization.Formatters sem suporte, que substitui a implementação de lançamento.

Qual é o risco de usar BinaryFormatter?

Qualquer desserializador, seja binário ou de texto, que permita que sua entrada carregue informações sobre os objetos a serem criados é um problema de segurança iminente. Há uma CWE (enumeração de fraqueza comum) que descreve o problema: CWE-502 "Desserialização de dados não confiáveis". BinaryFormatter, incluído na versão inicial do .NET Framework em 2002, é um desserializador. Também abordamos isso no guia de segurança BinaryFormater.

Devido aos riscos conhecidos de uso BinaryFormatter, a funcionalidade foi excluída do .NET Core 1.0. Mas sem um caminho de migração claro para usar algo mais seguro, a demanda do cliente levou a BinaryFormatter ser incluída no .NET Core 2.0. Desde então, a equipe do .NET está tentando remover o BinaryFormatter, desativando-o lentamente por padrão em vários tipos de projeto, mas permitindo que os usuários façam a ativação por meio de sinalizadores, se ainda necessário, para compatibilidade com versões anteriores.

Para obter mais detalhes sobre a decisão, consulte o BinaryFormatter que está sendo removido no comunicado do .NET 9 .

Se você encontrar problemas relacionados à remoção de BinaryFormatter que não estão resolvidos neste guia de migração, registre um problema em github.com/dotnet/runtime e indique que o problema está relacionado à remoção de BinaryFormatter.

Tópicos de migração

Migrar para longe BinaryFormatter geralmente significa escolher um serializador diferente. No entanto, isso geralmente só poderá ser feito se você controlar o produtor e o consumidor dos dados codificados. Caso não controle o produtor, você também pode migrar para nossa nova API para ler BinaryFormatter conteúdos sem instanciar nenhum dos tipos codificados.

Ambas as opções são exploradas abaixo.

Escolher um serializador

A primeira etapa da migração de BinaryFormatter é escolher um serializador a ser usado no lugar dele. Dependendo de suas necessidades específicas, a equipe do .NET recomenda migrações para quatro serializadores diferentes.

Leitura de cargas de BinaryFormatter (NRBF)

Muitos aplicativos carregam e desserializam cargas que foram mantidas no armazenamento e nem sempre é possível transformar todos os conteúdos persistentes antecipadamente. Outros cenários podem envolver sistemas ou serviços que recebem dados produzidos por BinaryFormatter, em que esses sistemas precisam ser migrados independentemente.

Nesses cenários e em outros, torna-se necessário manter o suporte para ler os conteúdos fornecidos e fazer a transição para um novo formato ao longo do tempo. Para satisfazer essas necessidades, agora é possível ler com segurança cargas NRBF criadas com BinaryFormatter sem executar a desserialização de uso geral e vulnerável.

Migrar aplicativos do Windows Forms e do WPF

Os aplicativos Windows Forms e WPF podem exigir alterações adicionais. Consulte os aplicativos do Windows Forms, os aplicativos do WPF, a área de transferência do WinForms/WPF e as diretrizes de arrastar e soltar para obter mais orientações de migração.

Migrar recursos gerenciados (ResX)

Os tipos de recursos mais comuns (como cadeias de caracteres e ícones) funcionarão sem BinaryFormatter. Para tipos personalizados, você precisa importar BinaryFormatter e ativar uma chave de compatibilidade. Consulte Carregando recurso durante o tempo de execução.

Usar o pacote de compatibilidade

Para cenários em que uma migração de BinaryFormatter não pode ser realizada no momento da atualização para o .NET 9, um pacote de compatibilidade sem suporte está disponível. O pacote NuGet System.Runtime.FormattersSerialization contém a implementação funcional de BinaryFormatter, incluindo suas vulnerabilidades e riscos.

Embora não tenha suporte e não seja recomendado, o guia para usar o pacote de compatibilidade inclui os detalhes para instalar o pacote e habilitar a funcionalidade.