Compartilhar via


Obsolescências na biblioteca de classes do .NET Framework

O .NET Framework mudou com o passar do tempo. Cada nova versão adicionou novos tipos e membros de tipo que ofereceram novas funcionalidades. Os tipos existentes e seus membros também mudaram com o passar do tempo. Por exemplo, alguns tipos se tornaram menos importantes conforme as tecnologias compatíveis foram sendo substituídas por novas tecnologias, e alguns métodos foram substituídos por métodos mais novos e melhores de certa forma.

O .NET Framework e o Common Language Runtime procuram dar suporte à compatibilidade com versões anteriores (permitindo que aplicativos desenvolvidos com uma versão do .NET Framework sejam executados na próxima versão do .NET Framework). Isso dificulta a simples remoção de um tipo ou de um membro de tipo. Em vez disso, o .NET Framework indicava que um tipo ou um membro de tipo não devia mais ser usado marcando-o como obsoleto ou preterido. Ao obsoletar um tipo ou membro, os desenvolvedores estavam cientes de que ele iria embora e tinham tempo para responder à sua remoção. No entanto, o código existente que usa o tipo ou o membro continua sendo executado na nova versão do .NET.

Observação

No .NET (Core), obsoletar uma API não significa necessariamente que a API será removida. Para saber mais, confira Remoção de API no .NET.

O atributo ObsoleteAttribute

O .NET Framework indica que um tipo ou um membro de tipo está obsoleto marcando-o com o atributo ObsoleteAttribute. A aplicação do atributo a um tipo ou um membro indica que esse tipo ou membro será removido em qualquer versão futura do .NET Framework sem interromper o código compilado que usa esse membro.

Além de indicar que um tipo ou membro de tipo é obsoleto, ObsoleteAttribute define como o compilador identifica o código-fonte que inclui esse tipo ou membro. O compilador pode compilar o código, mas emite uma mensagem de aviso, ou pode tratar o uso do tipo ou do membro como um erro. No primeiro caso, o código pode ser compilado com êxito, mas uma mensagem de aviso indica que o tipo ou o membro é obsoleto. No segundo caso, a compilação falha.

Mesmo se a compilação produzir um erro em vez de uma mensagem de aviso, o ObsoleteAttribute não afetará o comportamento do tempo de execução. Ou seja, os aplicativos que usam o tipo ou o membro e que são compilados com êxito sempre terão êxito. Somente a tentativa de recompilar um aplicativo que use o tipo ou o membro falha.

Como lidar com tipos e membros obsoletos

Quando você atualiza e depois recompila o código existente, o uso de um tipo ou de um membro obsoleto que produza um aviso do compilador em seu aplicativo é aceitável. No entanto, você deve examinar a mensagem de aviso do compilador para determinar se você deve alterar o código do aplicativo. Se a mensagem não apontar para uma alternativa adequada, você deverá fazer o seguinte:

  • Altere seu código removendo o uso do tipo ou do membro, se possível.

    -ou-

  • Examine a documentação dessa área de tecnologia para determinar como responder à substituição.

Você pode optar por não recompilar o código existente em comparação com uma versão posterior do .NET Framework. Em vez disso, você pode especificar a versão do .NET Framework na qual o código existente compilado é executado. Por exemplo, suponhamos que você tenha um aplicativo chamado app1.exe, compilado no .NET Framework 3.5, mas queira que o aplicativo seja executado no .NET Framework 4.5. Isso exige as seguintes etapas:

  1. Crie um arquivo de configuração para o executável principal e denomine-o appName.exe.config, em que appName é o nome do executável do aplicativo. Para o aplicativo chamado app1.exe em nosso exemplo, você criaria um arquivo de configuração chamado app1.exe.config.

  2. Adicione o seguinte ao arquivo de configuração.

    <configuration>
       <startup>
          <supportedRuntime version="v4.0" />
       </startup>
    </configuration>
    

Para direcionar uma versão específica de .NET Framework, atribua um dos seguintes valores de cadeia de caracteres ao atributo version:

Versão do .NET Framework Cadeia de caracteres version
4.8 (incluindo 4.8.1) v4.0
4.7 (incluindo 4.7.1 e 4.7.2) v4.0
4.6 (incluindo 4.6.1 e 4.6.2) v4.0
4.5 (incluindo 4.5.1 e 4.5.2) v4.0
4 v4.0
3,5 v2.0.50727
2,0 v2.0.50727
1,1 v1.1.4322
1,0 v1.0.3705

APIs obsoletas para o .NET Framework 4.5 e versões posteriores

APIs obsoletas para versões anteriores

Confira também