Plattformübergreifende ZieleCross-platform targeting

Modernes .NET unterstützt mehrere Betriebssysteme und Geräte.Modern .NET supports multiple operating systems and devices. Es ist wichtig, dass .NET-Open-Source-Bibliotheken so viele Entwickler wie möglich unterstützen, unabhängig davon, ob sie eine in Azure gehostete ASP.NET-Website oder ein .NET-Spiel in Unity erstellen.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 ist die beste Möglichkeit, plattformübergreifenden Support zu einer .NET-Bibliothek hinzuzufügen..NET Standard is the best way to add cross-platform support to a .NET library. .NET Standard ist eine Spezifikation von .NET-APIs, die für alle .NET-Implementierungen verfügbar sind..NET Standard is a specification of .NET APIs that are available on all .NET implementations. Wenn Sie Software für .NET Standard entwickeln, können Sie Bibliotheken erstellen, die nur APIs aus einer bestimmten Version von .NET Standard verwenden. Dies bedeutet, dass die Bibliotheken von allen Plattformen verwendet werden können, die diese Version von .NET Standard implementieren.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 .NET Standard.

.NET-Standard.NET Standard

Das Targeting von .NET Standard und die erfolgreiche Kompilierung Ihres Projekts garantieren nicht, dass die Bibliothek auf allen Plattformen erfolgreich läuft:Targeting .NET Standard, and successfully compiling your project, doesn't guarantee the library will run successfully on all platforms:

  1. Bei plattformspezifischen APIs tritt auf anderen Plattformen ein Fehler auf.Platform-specific APIs will fail on other platforms. Beispielsweise wird Microsoft.Win32.Registry unter Windows erfolgreich ausgeführt, gibt jedoch unter anderen Betriebssystemen PlatformNotSupportedException aus.For example, Microsoft.Win32.Registry will succeed on Windows and throw PlatformNotSupportedException when used on any other OS.
  2. APIs können sich unterschiedlich verhalten.APIs can behave differently. Beispielsweise haben Reflektions-APIs unterschiedliche Leistungsmerkmale, wenn eine Anwendung eine Ahead-of-time-Kompilierung auf iOS oder UWP verwendet.For example, reflection APIs have different performance characteristics when an application uses ahead-of-time compilation on iOS or UWP.

Tipp

Das .NET-Team bietet ein Roslyn-Analysetool zur Erkennung möglicher Probleme.The .NET team offers a Roslyn analyzer to help you discover possible issues.

✔️ Beginnen Sie, indem Sie ein netstandard2.0-Ziel einschließen.✔️ DO start with including a netstandard2.0 target.

Die meisten Bibliotheken für allgemeine Zwecke sollte außerhalb von .NET Standard 2.0 keine APIs erfordern.Most general-purpose libraries should not need APIs outside of .NET Standard 2.0. .NET Standard 2.0 wird von allen modernen Plattformen unterstützt und ist der empfohlene Weg, um mehrere Plattformen mit einem Ziel zu unterstützen..NET Standard 2.0 is supported by all modern platforms and is the recommended way to support multiple platforms with one target.

❌ Vermeiden Sie es, ein netstandard1.x-Ziel einzuschließen.❌ AVOID including a netstandard1.x target.

.NET Standard 1.x wird als ein granularer Satz von NuGet-Paketen verteilt, der ein großes Abhängigkeitsdiagramm erstellt und dazu führt, dass Entwickler beim Erstellen viele Pakete herunterladen..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. Moderne .NET-Implementierungen unterstützen .NET Standard 2.0.Modern .NET implementations support .NET Standard 2.0. Sie sollten.NET Standard 1.x nur dann als Ziel verwenden, wenn Sie speziell auf eine ältere Plattform abzielen müssen.You should only target .NET Standard 1.x if you specifically need to target an older platform.

✔️ Schließen Sie ein netstandard2.0-Ziel ein, wenn Sie ein netstandard1.x-Ziel benötigen.✔️ DO include a netstandard2.0 target if you require a netstandard1.x target.

Alle Plattformen, die .NET Standard 2.0 unterstützen, verwenden das netstandard2.0-Ziel und profitieren von einem kleineren Paketdiagramm, während ältere Plattformen noch funktionieren und auf die Verwendung des netstandard1.x-Ziels zurückgreifen.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.

❌ Fügen Sie kein .NET Standard-Ziel ein, wenn die Bibliothek auf einem plattformspezifischen App-Modell basiert.❌ DO NOT include a .NET Standard target if the library relies on a platform-specific app model.

Beispielsweise hängt eine Bibliothek eines UWP-Steuerelemente-Toolkit von einem Appmodell ab, das nur in UWP verfügbar ist.For example, a UWP control toolkit library depends on an app model that is only available on UWP. Appmodell-spezifische APIs sind nicht in .NET Standard verfügbar.App model specific APIs will not be available in .NET Standard.

Festlegung von ZielversionenMulti-targeting

Manchmal müssen über Ihre Bibliotheken auf Framework-spezifische APIs zugreifen.Sometimes you need to access framework-specific APIs from your libraries. Der beste Weg, Framework-spezifische APIs aufzurufen, ist die Verwendung der Festlegung von Zielversionen, das Ihr Projekt für viele .NET-Zielframeworks und nicht nur für eines erstellt.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.

Um Ihre Kunden davor zu schützen, Bibliotheken für einzelne Frameworks erstellen zu müssen, sollten Sie eine .NET Standard-Ausgabe sowie eine oder mehrere Framework-spezifische Ausgaben anstreben.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. Bei der Festlegung von Zielversionen werden alle Assemblys in einem einzigen NuGet-Paket verpackt.With multi-targeting, all assemblies are packaged inside a single NuGet package. Die Benutzer können dann auf das gleiche Paket zurückgreifen, und NuGet wählt die passende Implementierung aus.Consumers can then reference the same package and NuGet will pick the appropriate implementation. Ihre .NET Standard-Bibliothek dient als Fallbackbibliothek, die überall verwendet wird, mit Ausnahme der Fälle, in denen Ihr NuGet-Paket eine Framework-spezifische Implementierung bietet.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. Die Festlegung von Zielversionen ermöglicht es Ihnen, die bedingte Kompilierung in Ihrem Code zu verwenden und Framework-spezifische APIs aufzurufen.Multi-targeting allows you to use conditional compilation in your code and call framework-specific APIs.

NuGet-Paket mit mehreren AssemblysNuGet package with multiple assemblies

✔️ Erwägen Sie das Targeting von .NET-Implementierungen zusätzlich zu .NET Standard.✔️ CONSIDER targeting .NET implementations in addition to .NET Standard.

Das Targeting von .NET-Implementierungen ermöglichen es Ihnen, plattformspezifische APIs aufzurufen, die sich außerhalb von .NET-Standard befinden.Targeting .NET implementations allows you to call platform-specific APIs that are outside of .NET Standard.

Dabei muss weiterhin der Support für .NET Standard gewährleistet sein.Do not drop support for .NET Standard when you do this. Lösen Sie sich stattdessen von der Implementierung und bieten Sie Funktions-APIs.Instead, throw from the implementation and offer capability APIs. Auf diese Weise kann Ihre Bibliothek überall verwendet werden und unterstützt die Runtimehervorhebung von Funktionen.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
        }
    }
}

❌ Vermeiden Sie das Festlegen von mehreren Zielen sowie das Verwenden von .NET Standard als Ziel, wenn Ihr Quellcode für alle Ziele identisch ist.❌ AVOID multi-targeting as well as targeting .NET Standard, if your source code is the same for all targets.

Die .NET Standard-Assembly wird von NuGet automatisch verwendet.The .NET Standard assembly will automatically be used by NuGet. Das Targeting einzelner .NET-Implementierungen erhöht die *.nupkg-Größe, ohne dass sich daraus Vorteil ergeben.Targeting individual .NET implementations increases the *.nupkg size for no benefit.

✔️ Erwägen Sie, ein Ziel für net461 hinzuzufügen, wenn Sie ein netstandard2.0-Ziel anbieten.✔️ CONSIDER adding a target for net461 when you're offering a netstandard2.0 target.

Bei der Verwendung von .NET Standard 2.0 aus .NET Framework gibt es einige Probleme, die in .NET Framework 4.7.2 behoben wurden.Using .NET Standard 2.0 from .NET Framework has some issues that were addressed in .NET Framework 4.7.2. Sie können das Erlebnis für Entwickler, die noch mit .NET Framework 4.6.1 bis 4.7.1 arbeiten, verbessern, indem Sie ihnen eine Binärdatei anbieten, die für .NET Framework 4.6.1 erstellt wurde.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.

✔️ DO Verteilen Sie Ihre Bibliothek mithilfe eines NuGet-Pakets.✔️ DO distribute your library using a NuGet package.

NuGet wählt das beste Ziel für den Entwickler aus und schützt ihn davor, die passende Implementierung auswählen zu müssen.NuGet will select the best target for the developer and shield them having to pick the appropriate implementation.

✔️ Verwenden Sie bei der Festlegung von Zielversionen die TargetFrameworks-Eigenschaft der Projektdatei.✔️ 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>

✔ Erwägen Sie bei der Festlegung von Zielversionen für UWP und Xamarin die Verwendung von MSBuild.Sdk.Extras, da es Ihre Projektdatei stark vereinfacht.✔️ CONSIDER using MSBuild.Sdk.Extras when multi-targeting for UWP and Xamarin as it greatly simplifies your project file.

Ältere ZieleOlder targets

.NET unterstützt die Festlegung von Zielversionen des .NET Framework, die seit langem nicht mehr unterstützt werden, sowie Plattformen, die nur noch selten verwendet werden..NET supports targeting versions of .NET Framework that are long out of support as well as platforms that are no longer commonly used. Es ist zwar sinnvoll, Ihre Bibliothek mit so vielen Zielen wie möglich arbeiten zu lassen, aber die Notwendigkeit, fehlende APIs zu umgehen, kann zu einem erheblichen Aufwand führen.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. Wir glauben, dass bestimmte Frameworks angesichts ihrer Reichweite und Grenzen nicht mehr als Ziel genutzt werden sollten.We believe certain frameworks are no longer worth targeting, considering their reach and limitations.

❌ Schließen Sie keine portable Klassenbibliothek (PCL) als Ziel ein.❌ DO NOT include a Portable Class Library (PCL) target. Beispiel: portable-net45+win8+wpa81+wp8.For example, portable-net45+win8+wpa81+wp8.

.NET Standard ist die moderne Möglichkeit, um plattformübergreifende .NET-Bibliotheken zu unterstützen und ist der Ersatz für PCLs..NET Standard is the modern way to support cross-platform .NET libraries and replaces PCLs.

❌ Schließen Sie keine Ziele für .NET-Plattformen ein, die nicht mehr unterstützt werden.❌ DO NOT include targets for .NET platforms that are no longer supported. Platzhalter in einer derartigen Schreibweise sind z.B. SL4 und WP.For example, SL4, WP.