Usar o Pacote de Compatibilidade do Windows para fazer a portabilidade pra o .NET CoreUse the Windows Compatibility Pack to port code to .NET Core

Alguns dos problemas mais comuns durante a portabilidade do código existente para o .NET Core são as dependências de APIs e tecnologias encontradas apenas no .NET Framework.Some of the most common issues found when porting existing code to .NET Core are dependencies on APIs and technologies that are only found in the .NET Framework. O Pacote de Compatibilidade do Windows fornece muitas dessas tecnologias, portanto, é muito mais fácil compilar aplicativos .NET Core e bibliotecas do .NET Standard.The Windows Compatibility Pack provides many of these technologies, so it's much easier to build .NET Core applications and .NET Standard libraries.

Esse pacote é uma extensão lógica do .NET Standard 2.0 que aumenta consideravelmente o conjunto de APIs e o código existente é compilado quase sem modificações.This package is a logical extension of .NET Standard 2.0 that significantly increases API set and existing code compiles with almost no modifications. No entanto, para manter a promessa do .NET Standard (“é o conjunto de APIs fornecido por todas as implementações do .NET”), isso não inclui tecnologias que não funcionam em todas as plataformas, como o Registro, o WMI (Instrumentação de Gerenciamento do Windows) ou as APIs de emissão de reflexão.But in order to keep the promise of .NET Standard ("it is the set of APIs that all .NET implementations provide"), this didn't include technologies that can't work across all platforms, such as registry, Windows Management Instrumentation (WMI), or reflection emit APIs.

O Pacote de Compatibilidade do Windows se baseia no .NET Standard e fornece acesso às tecnologias somente Windows.The Windows Compatibility Pack sits on top of .NET Standard and provides access to technologies that are Windows only. É especialmente útil para os clientes que desejam migrar para o .NET Core, mas pretendem permanecer no Windows como uma primeira etapa.It's especially useful for customers that want to move to .NET Core but plan to stay on Windows as a first step. Nesse cenário, não conseguir usar as tecnologias somente Windows é apenas um obstáculo de migração sem nenhum benefício de arquitetura.In that scenario, not being able to use Windows-only technologies is only a migration hurdle with zero architectural benefits.

Conteúdo do pacotePackage contents

O Pacote de Compatibilidade do Windows é fornecido por meio do Pacote NuGet Microsoft.Windows.Compatibility e pode ser referenciado em projetos direcionados ao .NET Core ou .NET Standard.The Windows Compatibility Pack is provided via the NuGet Package Microsoft.Windows.Compatibility and can be referenced from projects targeting .NET Core or .NET Standard.

Ele fornece cerca de 20.000 APIs, incluindo APIs somente Windows, bem como APIs de multiplataforma das seguintes áreas de tecnologia:It provides about 20,000 APIs, including Windows-only as well as cross-platform APIs from the following technology areas:

  • Páginas de códigoCode Pages
  • CodeDomCodeDom
  • ConfiguraçãoConfiguration
  • Serviços de DiretórioDirectory Services
  • DesenhoDrawing
  • ODBCODBC
  • PermissõesPermissions
  • PortasPorts
  • ACL (Listas de Controle de Acesso) do WindowsWindows Access Control Lists (ACL)
  • Windows Communication Foundation (WCF)Windows Communication Foundation (WCF)
  • Criptografia do WindowsWindows Cryptography
  • EventLog do WindowsWindows EventLog
  • WMI (Instrumentação de Gerenciamento do Windows)Windows Management Instrumentation (WMI)
  • Contadores de Desempenho do WindowsWindows Performance Counters
  • Registro do WindowsWindows Registry
  • Cache do Windows RuntimeWindows Runtime Caching
  • Serviços WindowsWindows Services

Para obter mais informações, confira a especificação do pacote de compatibilidade.For more information, see the specification of the compatibility pack.

IntroduçãoGet started

  1. Antes da portabilidade, examine o Processo de portabilidade.Before porting, make sure to take a look at the Porting Process.

  2. Ao portar um código existente para o .NET Core ou .NET Standard, instale o pacote NuGet Microsoft.Windows.Compatibility.When porting existing code to .NET Core or .NET Standard, install the NuGet package Microsoft.Windows.Compatibility.

  3. Caso deseje permanecer no Windows, você estará pronto.If you want to stay on Windows, you're all set.

  4. Se desejar executar o aplicativo .NET Core ou a biblioteca .NET Standard no Linux ou macOS, use o Analisador de API para localizar o uso de APIs que não funcionarão com multiplataforma.If you want to run the .NET Core application or .NET Standard library on Linux or macOS, use the API Analyzer to find usage of APIs that won't work cross-platform.

  5. Remova os usos dessas APIs, substitua-os por alternativas de multiplataforma ou proteja-os usando uma verificação de plataforma, como:Either remove the usages of those APIs, replace them with cross-platform alternatives, or guard them using a platform check, like:

    private static string GetLoggingPath()
    {
        // Verify the code is running on Windows.
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        {
            using (var key = Registry.CurrentUser.OpenSubKey(@"Software\Fabrikam\AssetManagement"))
            {
                if (key?.GetValue("LoggingDirectoryPath") is string configuredPath)
                    return configuredPath;
            }
        }
    
        // This is either not running on Windows or no logging path was configured,
        // so just use the path for non-roaming user-specific data files.
        var appDataPath = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
        return Path.Combine(appDataPath, "Fabrikam", "AssetManagement", "Logging");
    }
    

Para ver uma demonstração, confira o vídeo do Channel 9 sobre o Pacote de Compatibilidade do Windows.For a demo, check out the Channel 9 video of the Windows Compatibility Pack.