Utilisation du pack de compatibilité WindowsUsing the Windows Compatibility Pack

L’un des problèmes les plus courants auxquels les développeurs sont confrontés lors du portage de leur code existant vers .NET Core est qu’ils dépendent des API et des technologies qui existent uniquement dans le .NET Framework.One of the most common issues that developers face when porting their existing code to .NET Core is that they depend on APIs and technologies that only exist in the .NET Framework. Le pack de compatibilité Windows se rapporte à la mise à disposition d’un grand nombre de ces technologies afin que la création d’applications .NET Core et de bibliothèques .NET Standard devienne beaucoup plus viable pour le code existant.The Windows Compatibility Pack is about providing many of these technologies so that building .NET Core applications as well as .NET Standard libraries becomes much more viable for existing code.

Ce package est une extension logique de.NET Standard 2.0 qui augmente considérablement l’ensemble d’API et le code existant est compilé sans presque aucune modification.This package is a logical extension of .NET Standard 2.0 that significantly increases API set and existing code compiles with almost no modifications. Toutefois, pour respecter l’engagement de .NET Standard (« il s’agit de l’ensemble d’API fourni par toutes les implémentations .NET »), cela ne comprend pas les technologies qui ne peuvent pas fonctionner sur toutes les plateformes, telles que le Registre, WMI (Windows Management Instrumentation), ou les API d’émission de réflexion.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.

Le pack de compatibilité Windows repose sur .NET Standard et permet d’accéder aux technologies Windows uniquement.The Windows Compatibility Pack sits on top of .NET Standard and provides access to technologies that are Windows only. Il est particulièrement utile pour les clients qui veulent passer à .NET Core, mais envisagent de rester sur Windows pour commencer.It's especially useful for customers that want to move to .NET Core but plan to stay on Windows as a first step. Dans ce scénario, le fait de ne pas pouvoir utiliser les technologies Windows uniquement est juste un obstacle à la migration sans aucun avantage en matière d’architecture.In that scenario, not being able to use Windows-only technologies is only a migration hurdle with zero architectural benefits.

Contenu du packagePackage contents

Le pack de compatibilité Windows est fourni via le package NuGet Microsoft.Windows.Compatibility et peut être référencé à partir de projets ciblant .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.

Il fournit environ 20 000 API, dont des API Windows uniquement ainsi des API multiplateformes des domaines technologiques suivants :It provides about 20,000 APIs, including Windows-only as well as cross-platform APIs from the following technology areas:

  • Pages de codesCode Pages
  • CodeDomCodeDom
  • ConfigurationConfiguration
  • Services d'annuaireDirectory Services
  • DessinDrawing
  • ODBCODBC
  • AutorisationsPermissions
  • PortsPorts
  • Listes de contrôle d’accès WindowsWindows Access Control Lists (ACL)
  • Windows Communication Foundation (WCF)Windows Communication Foundation (WCF)
  • Chiffrement WindowsWindows Cryptography
  • Journal des événements WindowsWindows EventLog
  • WMI (Windows Management Instrumentation)Windows Management Instrumentation (WMI)
  • Compteurs de performances WindowsWindows Performance Counters
  • Registre WindowsWindows Registry
  • Mise en cache Windows RuntimeWindows Runtime Caching
  • services WindowsWindows Services

Pour plus d’informations, consultez la spécification du pack de compatibilité.For more information, see the spec of the compatibility pack.

Prise en mainGet started

  1. Avant le portage, veillez à examiner le processus de portage.Before porting, make sure to take a look at the Porting Process.

  2. Lors du portage du code existant vers .NET Core ou .NET Standard, installez le package NuGet Microsoft.Windows.Compatibility.When porting existing code to .NET Core or .NET Standard, install the NuGet package Microsoft.Windows.Compatibility.

  3. Si vous souhaitez rester sur Windows, vous êtes prêt.If you want to stay on Windows, you're all set.

  4. Si vous souhaitez exécuter l’application .NET Core ou la bibliothèque .NET Standard sur Linux ou macOS, utilisez l’analyseur d’API pour trouver l’usage des API qui ne fonctionnent pas sur toutes les plateformes.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. Supprimez les usages de ces API, remplacez-les par des alternatives multiplateformes ou protégez-les à l’aide d’une vérification de la plateforme, par exemple :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");
    }
    

Pour obtenir une démonstration, regardez la vidéo de Channel 9 sur le pack de compatibilité Windows.For a demo, check out the Channel 9 video of the Windows Compatibility Pack.