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 encontrados ao portar o código existente para o .NET Core são dependências de APIs e tecnologias que só são encontradas 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 .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.

O pacote de compatibilidade é uma extensão lógica do .NET Standard 2.0 que aumenta significativamente o conjunto de API.The compatibility pack is a logical extension of .NET Standard 2.0 that significantly increases the API set. O código existente compila quase nenhuma modificação.Existing code compiles with almost no modifications. Para manter sua promessa de "o conjunto de APIs que todas as implementações .NET fornecem", o .NET Standard não inclui tecnologias que não podem funcionar em todas as plataformas, como registro, Instrumentação de Gerenciamento do Windows (WMI) ou APIs de reflexão.To keep its promise of "the set of APIs that all .NET implementations provide", .NET Standard doesn'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 fica em cima do .NET Standard e fornece acesso a essas tecnologias somente para Windows.The Windows Compatibility Pack sits on top of .NET Standard and provides access to these Windows-only technologies. É especialmente útil para clientes que querem mudar para o .NET Core, mas planejam permanecer no Windows, pelo menos como um primeiro passo.It's especially useful for customers that want to move to .NET Core but plan to stay on Windows, at least as a first step. Nesse cenário, poder usar tecnologias somente para Windows remove o obstáculo de migração.In that scenario, being able to use Windows-only technologies removes the migration hurdle.

Conteúdo do pacotePackage contents

O Pacote de Compatibilidade do Windows é fornecido através do pacote Microsoft.Windows.Compatibility NuGet e pode ser referenciado a partir de projetos que visam .NET Core ou .NET Standard.The Windows Compatibility Pack is provided via the Microsoft.Windows.Compatibility NuGet package and can be referenced from projects that target .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
  • ODBCODBCODBC
  • 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 de portar, certifique-se de dar uma olhada no processo de portação.Before porting, make sure to take a look at the Porting process.

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

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

  3. 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.

  4. 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.