Ciblage multiplateformeCross-platform targeting

L’infrastructure .NET moderne prend en charge plusieurs systèmes d’exploitation et appareils.Modern .NET supports multiple operating systems and devices. Il est important que les bibliothèques .NET open source prennent en charge autant de développeurs que possible, que ce soit pour développer un site Web ASP.NET hébergé dans Azure ou un jeu .NET dans Unity.It's important for .NET open-source libraries to support as many developers as possible, whether they're building an ASP.NET website hosted in Azure, or a .NET game in Unity.

.NET Standard.NET Standard

.NET Standard est la meilleure façon d’ajouter une prise en charge multiplateforme à une bibliothèque .NET..NET Standard is the best way to add cross-platform support to a .NET library. .NET Standard est une spécification des API .NET disponibles sur toutes les implémentations de .NET..NET Standard is a specification of .NET APIs that are available on all .NET implementations. Le ciblage .NET Standard vous permet de générer des bibliothèques contraintes d’utiliser des API qui se trouvent dans une version donnée de .NET Standard, ce qui signifie qu’il est utilisable par toutes les plateformes qui implémentent cette version de .NET Standard.Targeting .NET Standard lets you produce libraries that are constrained to use APIs that are in a given version of .NET Standard, which means it's usable by all platforms that implement that version of the .NET Standard.

.NET Standard.NET Standard

Le ciblage .NET Standard et la compilation avec succès de votre projet ne garantissent pas que la bibliothèque fonctionne correctement sur toutes les plateformes :Targeting .NET Standard, and successfully compiling your project, doesn't guarantee the library will run successfully on all platforms:

  1. des API propres à une plateforme échoueront sur d’autres plateformes.Platform-specific APIs will fail on other platforms. Par exemple, Microsoft.Win32.Registry réussiront sur Windows mais lèveront une exception PlatformNotSupportedException s’ils sont utilisés sur n’importe quel autre système d’exploitation.For example, Microsoft.Win32.Registry will succeed on Windows and throw PlatformNotSupportedException when used on any other OS.
  2. Les API peuvent se comporter différemment.APIs can behave differently. Par exemple, les API de réflexion ont des caractéristiques de performances différentes lorsqu’une application utilise la compilation AOT (Ahead Of Time) sur iOS ou UWP.For example, reflection APIs have different performance characteristics when an application uses ahead-of-time compilation on iOS or UWP.

Conseil

L’équipe .NET propose un analyseur Roslyn pour vous aider à détecter les éventuels problèmes.The .NET team offers a Roslyn analyzer to help you discover possible issues.

✔️ commencer par, y compris une cible de netstandard2.0.✔️ DO start with including a netstandard2.0 target.

La plupart des bibliothèques à usage général ne devraient pas avoir besoin d’API en dehors de .NET Standard 2.0.Most general-purpose libraries should not need APIs outside of .NET Standard 2.0. .NET Standard 2.0 est pris en charge par toutes les plateformes modernes et constitue la méthode recommandée pour prendre en charge plusieurs plateformes avec une cible..NET Standard 2.0 is supported by all modern platforms and is the recommended way to support multiple platforms with one target.

❌ éviter d’inclure une cible de netstandard1.x.❌ AVOID including a netstandard1.x target.

.NET Standard 1.x est distribué sous la forme d’un ensemble précis de packages NuGet, qui crée un grand graphique des dépendances de package et amène les développeurs à télécharger un grand nombre de packages lors de la génération..NET Standard 1.x is distributed as a granular set of NuGet packages, which creates a large package dependency graph and results in developers downloading a lot of packages when building. Les plateformes .NET modernes, y compris .NET Framework 4.6.1, UWP et Xamarin, prennent toutes en charge .NET Standard 2.0.Modern .NET platforms, including .NET Framework 4.6.1, UWP and Xamarin, all support .NET Standard 2.0. Vous devez uniquement cibler .NET Standard 1.x si vous avez besoin de cibler une plateforme plus ancienne.You should only target .NET Standard 1.x if you specifically need to target an older platform.

✔️ inclure une cible de netstandard2.0 si vous avez besoin d’une cible netstandard1.x.✔️ DO include a netstandard2.0 target if you require a netstandard1.x target.

Toutes les plateformes prenant en charge .NET Standard 2.0 utiliseront la cible netstandard2.0 et bénéficieront d’un graphique de packages plus petit, tandis que les anciennes plateformes continueront de fonctionner et utiliseront la cible netstandard1.x.All platforms supporting .NET Standard 2.0 will use the netstandard2.0 target and benefit from having a smaller package graph while older platforms will still work and fall back to using the netstandard1.x target.

❌ n’incluez pas de cible .NET Standard si la bibliothèque s’appuie sur un modèle d’application spécifique à la plateforme.❌ DO NOT include a .NET Standard target if the library relies on a platform-specific app model.

Par exemple, une bibliothèque de boîte à outils de contrôle UWP dépend d’un modèle d’application uniquement disponible sur UWP.For example, a UWP control toolkit library depends on an app model that is only available on UWP. Les API spécifiques à un modèle d’application ne seront pas disponibles dans .NET Standard.App model specific APIs will not be available in .NET Standard.

Multi-ciblageMulti-targeting

Parfois, vous avez besoin accéder à des API spécifiques à une infrastructure à partir de vos bibliothèques.Sometimes you need to access framework-specific APIs from your libraries. La meilleure façon d’appeler des API spécifiques à une infrastructure consiste à utiliser le multi-ciblage, qui génère votre projet pour un grand nombre d’infrastructures .NET cible plutôt que pour une seule.The best way to call framework-specific APIs is using multi-targeting, which builds your project for many .NET target frameworks rather than for just one.

Pour éviter à vos consommateurs d’avoir à créer pour chaque infrastructure, vous devez vous efforcer d’avoir une sortie Standard .NET ainsi qu’une ou plusieurs sorties spécifiques à l’infrastructure.To shield your consumers from having to build for individual frameworks, you should strive to have a .NET Standard output plus one or more framework-specific outputs. Avec le multi-ciblage, tous les assemblys sont empaquetés dans un même package NuGet.With multi-targeting, all assemblies are packaged inside a single NuGet package. Les consommateurs peuvent ensuite référencer le même package, et NuGet choisit l’implémentation appropriée.Consumers can then reference the same package and NuGet will pick the appropriate implementation. Votre bibliothèque .NET Standard sert de bibliothèque de secours utilisée partout, sauf si votre package NuGet offre une implémentation spécifique à une infrastructure.Your .NET Standard library serves as the fallback library that is used everywhere, except for the cases where your NuGet package offers a framework-specific implementation. Le multi-ciblage permet d’utiliser la compilation conditionnelle dans votre code et d’appeler des API spécifiques à une infrastructure.Multi-targeting allows you to use conditional compilation in your code and call framework-specific APIs.

Package NuGet avec plusieurs assemblysNuGet package with multiple assemblies

✔️ ENVISAGER de cibler des implémentations .NET en plus des .NET Standard.✔️ CONSIDER targeting .NET implementations in addition to .NET Standard.

Le ciblage d’implémentations .NET vous permet d’appeler des API spécifiques à la plateforme qui sont trouvent en dehors de .NET Standard.Targeting .NET implementations allows you to call platform-specific APIs that are outside of .NET Standard.

Ne supprimez pas la prise en charge de .NET Standard lorsque vous effectuez cette opération.Do not drop support for .NET Standard when you do this. Au lieu de cela, levez une exception à partir de l’implémentation et offrez la fonctionnalité API.Instead, throw from the implementation and offer capability APIs. De cette façon, votre bibliothèque peut être utilisée partout et prend en charge le runtime des fonctionnalités.This way, your library can be used anywhere and supports runtime light-up of features.

public static class GpsLocation
{
    // This project uses multi-targeting to expose device-specific APIs to .NET Standard.
    public static async Task<(double latitude, double longitude)> GetCoordinatesAsync()
    {
#if NET461
        return CallDotNetFramworkApi();
#elif WINDOWS_UWP
        return CallUwpApi();
#else
        throw new PlatformNotSupportedException();
#endif
    }

    // Allows callers to check without having to catch PlatformNotSupportedException
    // or replicating the OS check.
    public static bool IsSupported
    {
        get
        {
#if NET461 || WINDOWS_UWP
            return true;
#else
            return false;
#endif
        }
    }
}

❌ éviter le multi-ciblage et le ciblage .NET Standard, si votre code source est le même pour toutes les cibles.❌ AVOID multi-targeting as well as targeting .NET Standard, if your source code is the same for all targets.

L’assembly .NET Standard sera automatiquement utilisé par NuGet.The .NET Standard assembly will automatically be used by NuGet. Le ciblage d’implémentations .NET individuelles augmente la taille *.nupkg sans apporter d’avantage.Targeting individual .NET implementations increases the *.nupkg size for no benefit.

✔️ envisagez d’ajouter une cible pour net461 quand vous offrez une netstandard2.0 cible.✔️ CONSIDER adding a target for net461 when you're offering a netstandard2.0 target.

L’utilisation de .NET Standard 2.0 dans .NET Framework entraîne certains problèmes qui ont été résolus dans .NET Framework 4.7.2.Using .NET Standard 2.0 from .NET Framework has some issues that were addressed in .NET Framework 4.7.2. Vous pouvez améliorer l’expérience des développeurs qui utilisent toujours .NET Framework 4.6.1 - 4.7.1 en leur offrant un fichier binaire conçu pour .NET Framework 4.6.1.You can improve the experience for developers that are still on .NET Framework 4.6.1 - 4.7.1 by offering them a binary that is built for .NET Framework 4.6.1.

✔️ distribuer votre bibliothèque à l’aide d’un package NuGet.✔️ DO distribute your library using a NuGet package.

NuGet sélectionnera la meilleure cible pour les développeurs et leur évitera d’avoir à choisir l’implémentation appropriée.NuGet will select the best target for the developer and shield them having to pick the appropriate implementation.

✔️ Utilisez la propriété TargetFrameworks d’un fichier projet en cas de multi-ciblage.✔️ DO use a project file's TargetFrameworks property when multi-targeting.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- This project will output netstandard2.0 and net461 assemblies -->
    <TargetFrameworks>netstandard2.0;net461</TargetFrameworks>
  </PropertyGroup>
</Project>

✔️ envisagez d’utiliser MSBuild. Sdk. Extras lors du MULTICIBLAGE pour UWP et Xamarin, car cela simplifie grandement votre fichier projet.✔️ CONSIDER using MSBuild.Sdk.Extras when multi-targeting for UWP and Xamarin as it greatly simplifies your project file.

Anciennes ciblesOlder targets

.NET prend en charge le ciblage de versions .NET Framework qui ne sont plus prises en charge depuis longtemps, ainsi que les plateformes qui ne sont plus couramment utilisées..NET supports targeting versions of the .NET Framework that are long out of support as well as platforms that are no longer commonly used. Bien qu'il soit utile de faire fonctionner votre bibliothèque sur autant de cibles que possible, le fait de devoir contourner des API manquantes peut entraîner d’importants frais généraux.While there's value in making your library work on as many targets as possible, having to work around missing APIs can add significant overhead. Nous estimons que certaines infrastructures ne valent plus la peine d'être ciblées, compte tenu de leur portée et de leurs limites.We believe certain frameworks are no longer worth targeting, considering their reach and limitations.

❌ n’incluez pas une cible de bibliothèque de classes portable (PCL).❌ DO NOT include a Portable Class Library (PCL) target. Par exemple, portable-net45+win8+wpa81+wp8.For example, portable-net45+win8+wpa81+wp8.

.NET standard est la méthode moderne de prendre en charge les bibliothèques .NET multiplateformes et remplace les PCL..NET Standard is the modern way to support cross-platform .NET libraries and replaces PCLs.

❌ n’incluez pas de cibles pour les plateformes .NET qui ne sont plus prises en charge.❌ DO NOT include targets for .NET platforms that are no longer supported. Par exemple, SL4, WP.For example, SL4, WP.