Fehlende .NET-APIs in Unity und UWPMissing .NET APIs in Unity and UWP

Wenn Sie ein UWP-Spiel mit .NET entwickeln, werden Sie möglicherweise feststellen, dass einige APIs, die Sie möglicherweise im Unity-Editor oder für ein eigenständiges PC-Spiel verwenden, nicht für UWP vorhanden sind.When building a UWP game using .NET, you may find that some APIs that you might use in the Unity editor or for a standalone PC game are not present for UWP. Dies liegt daran, dass .net für UWP-apps eine Teilmenge der Typen enthält, die im vollständigen .NET Framework für jeden Namespace bereitgestellt werden.That's because .NET for UWP apps includes a subset of the types provided in the full .NET Framework for each namespace.

Darüber hinaus verwenden einige Spiel-Engines verschiedene .NET-Versionen, die nicht vollständig mit .net für UWP kompatibel sind, wie z. b. das Mono von Unity.Additionally, some game engines use different flavors of .NET that aren't fully compatible with .NET for UWP, such as Unity's Mono. Wenn Sie also Ihr Spiel schreiben, kann alles im Editor einwandfrei funktionieren. Wenn Sie jedoch den Build für UWP verwenden, erhalten Sie möglicherweise Fehler wie die folgende: der Typ oder Namespace "Formatierer" ist im Namespace "System. Runtime. Serialization" nicht vorhanden (fehlt ein Assemblyverweis?)So when you're writing your game, everything might work fine in the editor, but when you go to build for UWP, you might get errors like this: The type or namespace 'Formatters' does not exist in the namespace 'System.Runtime.Serialization' (are you missing an assembly reference?)

Glücklicherweise stellt Unity einige dieser fehlenden APIs als Erweiterungs Methoden und Ersetzungs Typen bereit, die unter universelle Windows-Plattform: fehlende .NET-Typen im .NET-Skript-Back-End beschrieben werden.Fortunately, Unity provides some of these missing APIs as extension methods and replacement types, which are described in Universal Windows Platform: Missing .NET Types on .NET Scripting Backend. Wenn die von Ihnen benötigte Funktionalität jedoch nicht hier aufgeführt ist, wird in der Übersicht über .net für Windows 8. x-apps erläutert, wie Sie Ihren Code für die Verwendung von WinRT oder .net für Windows-Runtime-APIs konvertieren können.However, if the functionality you need is not here, .NET for Windows 8.x apps overview discusses ways you can convert your code to use WinRT or .NET for Windows Runtime APIs. (In diesem Thema wird Windows 8 erläutert, es gilt aber auch für Windows 10-UWP-apps.)(It discusses Windows 8, but is applicable to Windows 10 UWP apps as well.)

.NET Standard.NET Standard

Um zu verstehen, warum einige APIs möglicherweise nicht funktionieren, ist es wichtig, sich mit den verschiedenen .net-Varianten und der Implementierung von .net von UWP vertraut zu machen.To understand why some APIs might not be working, it's important to understand the different .NET flavors and how UWP implements .NET. Der .NET Standard ist eine formale Spezifikation von .NET-APIs, die plattformübergreifend sein sollen, und die verschiedenen .net-Varianten vereinheitlichen.The .NET Standard is a formal specification of .NET APIs that is meant to be cross-platform, and unify the different .NET flavors. Jede Implementierung von .NET unterstützt eine bestimmte Version der .NET Standard.Each implementation of .NET supports a certain version of the .NET Standard. Eine Tabelle mit Standards und Implementierungen finden Sie unter Unterstützung der .NET-Implementierung.You can see a table of standards and implementations at .NET implementation support.

Jede Version des UWP SDK entspricht einer anderen .NET Standard Ebene.Each version of the UWP SDK conforms to a different level of .NET Standard. Beispielsweise unterstützt das 16299 SDK (das Fall Creators Update) .NET Standard 2,0.For example, the 16299 SDK (the Fall Creators Update) supports .NET Standard 2.0.

Wenn Sie wissen möchten, ob eine bestimmte .NET-API in der UWP-Version unterstützt wird, die Sie als Ziel verwenden, können Sie die .NET Standard-API-Referenz überprüfen und die Version der .NET Standard auswählen, die von dieser Version von UWP unterstützt wird.If you want to know if a certain .NET API is supported in the UWP version that you're targeting, you can check the .NET Standard API Reference and select the version of the .NET Standard that's supported by that version of UWP.

Skripterstellung für BackendScripting backend configuration

Wenn Sie Probleme beim Erstellen von UWP haben, müssen Sie zunächst die Player Einstellungen überprüfen (Datei > Buildeinstellungen, wählen Sie universelle Windows-Plattformund dann Spieler Einstellungen).The first thing you should do if you're having trouble building for UWP is check the Player Settings (File > Build Settings, select Universal Windows Platform, and then Player Settings). Unter anderen Einstellungen > Konfigurationsind die ersten drei Dropdown Listen (Skript-Lauf Zeit Version, Skript-Back-End und API-Kompatibilitäts Grad) alle wichtigen Einstellungen zu beachten.Under Other Settings > Configuration, the first three dropdowns (Scripting Runtime Version, Scripting Backend, and Api Compatibility Level) are all important settings to consider.

Die Skripting-Laufzeitversion verwendet das Unity-Skript-Back-End, mit dem Sie die (ungefähr) gleichwertige Version .NET Framework von Ihnen ausgewählten Unterstützung erhalten können.The Scripting Runtime Version is what the Unity scripting backend uses which allows you to get the (roughly) equivalent version of .NET Framework support that you choose. Beachten Sie jedoch, dass nicht alle APIs in dieser Version der .NET Framework unterstützt werden, sondern nur die APIs in der Version von .NET Standard, für die ihre UWP als Ziel verwendet wird.However, keep in mind that not all APIs in that version of the .NET Framework will be supported, only those in the version of .NET Standard that your UWP is targeting.

Häufig werden bei neuen .NET-Releases weitere APIs zu .NET Standard hinzugefügt, die es Ihnen ermöglichen, den gleichen Code für eigenständige und UWP zu verwenden.Often with new .NET releases, more APIs are added to .NET Standard which might allow you to use the same code across standalone and UWP. Beispielsweise wurde die System.Runtime.Serialization.Js für den Namespace in .NET Standard 2,0 eingeführt.For example, the System.Runtime.Serialization.Json namespace was introduced in .NET Standard 2.0. Wenn Sie die CLR- Laufzeitversion auf .NET 3,5-Äquivalent festlegen (was auf eine frühere Version der .NET Standard abzielt), erhalten Sie eine Fehlermeldung, wenn Sie versuchen, die API zu verwenden. Wechseln Sie zur .NET 4,6-Entsprechung (die .NET Standard 2,0 unterstützt), und die API funktioniert.If you set the Scripting Runtime Version to .NET 3.5 Equivalent (which targets an earlier version of the .NET Standard), you will get an error when trying to use the API; switch it to .NET 4.6 Equivalent (which supports .NET Standard 2.0), and the API will work.

Das Skript für die Skripterstellung kann .net oder IL2CPPsein.The Scripting Backend can be .NET or IL2CPP. In diesem Thema wird davon ausgegangen, dass Sie .netausgewählt haben, da hier die hier beschriebenen Probleme auftreten.For this topic, we assume you have chosen .NET, since that's where the problems discussed here arise. Weitere Informationen finden Sie unter Skripting-Back-Ends .See Scripting Backends for more information.

Schließlich sollten Sie den API- Kompatibilitäts Grad auf die Version von .net festlegen, auf der das Spiel ausgeführt werden soll.Finally, you should set the Api Compatibility Level to the version of .NET that you want your game to run on. Dies sollte der Skript Lauf Zeit Versionentsprechen.This should match the Scripting Runtime Version.

Im Allgemeinen sollten Sie für die Skript Laufzeit-Version und den API-Kompatibilitäts Graddie neueste verfügbare Version auswählen, um eine höhere Kompatibilität mit dem .NET Framework zu ermöglichen und so die Verwendung von weiteren .NET-APIs zu ermöglichen.In general, for Scripting Runtime Version and Api Compatibility Level, you should select the latest version available so as to have more compatibility with the .NET Framework, and thus allow you to use more .NET APIs.

Konfiguration: Skripterstellung für Lauf Zeit Version; Skripterstellung für Backend API-Kompatibilitäts Grad

Platt Form abhängige KompilierungPlatform-dependent compilation

Wenn Sie Ihr Unity-Spiel für mehrere Plattformen erstellen, einschließlich UWP, sollten Sie eine Platt Form abhängige Kompilierung verwenden, um sicherzustellen, dass der für UWP vorgesehene Code nur ausgeführt wird, wenn das Spiel als UWP erstellt wird.If you're building your Unity game for multiple platforms, including UWP, you'll want to use platform-dependent compilation to make sure that code intended for UWP is only run when the game is built as a UWP. Auf diese Weise können Sie die vollständige .NET Framework für eigenständige Desktops und andere Plattformen sowie WinRT-APIs für UWP verwenden, ohne Buildfehler zu erhalten.This way, you can use the full .NET Framework for standalone desktop and other platforms, and WinRT APIs for UWP, without getting build errors.

Verwenden Sie die folgenden Direktiven, um beim Ausführen als UWP-app nur Code zu kompilieren:Use the following directives to only compile code when running as a UWP app:

#if NETFX_CORE
    // Your UWP code here
#else
    // Your standard code here
#endif

Hinweis

NETFX_CORE dient nur dazu, zu überprüfen, ob Sie c#-Code für das .NET-Skript-Back-End kompilieren.NETFX_CORE is only meant to check if you're compiling C# code against the .NET scripting backend. Wenn Sie ein anderes Skript für die Skripterstellung verwenden, z. b. IL2CPP, verwenden Sie ENABLE_WINMD_SUPPORT stattdessen.If you're using a different scripting backend, such as IL2CPP, use ENABLE_WINMD_SUPPORT instead.

Eine vollständige Liste der Platt Form abhängigen Kompilierungs Direktiven finden Sie unter Platt Form abhängige Kompilierung.For the full list of platform-dependent compilation directives, see Platform dependent compilation.

Häufig auftretende Probleme und ProblemumgehungenCommon issues and workarounds

In den folgenden Szenarien werden häufige Probleme beschrieben, die auftreten können, wenn .NET-APIs in der UWP-Teilmenge fehlen, und Möglichkeiten, Sie zu umgehen.The following scenarios describe common issues that might arise where .NET APIs are missing from the UWP subset, and ways to get around them.

Datenserialisierung mit BinaryFormatterData serialization using BinaryFormatter

Spiele werden häufig zum Serialisieren von Daten gespeichert, sodass Sie von den Playern nicht einfach bearbeitet werden können.It is common for games to serialize save data so that players can't easily manipulate it. Allerdings ist BinaryFormatter, der ein Objekt in Binärdateien serialisiert, nicht in früheren Versionen des .NET Standard (vor 2,0) verfügbar.However, BinaryFormatter, which serializes an object into binary, is not available in earlier versions of the .NET Standard (prior to 2.0). Verwenden Sie stattdessen XmlSerializer oder DataContractJsonSerializer .Consider using XmlSerializer or DataContractJsonSerializer instead.

private void Save()
{
    SaveData data = new SaveData(); // User-defined object to serialize

    DataContractJsonSerializer serializer = 
      new DataContractJsonSerializer(typeof(SaveData));

    FileStream stream = 
      new FileStream(Application.persistentDataPath, FileMode.CreateNew);

    serializer.WriteObject(stream, data);
    stream.Dispose();
}

E/A-VorgängeI/O operations

Einige Typen im System.IO -Namespace, z. b. FileStream, sind in früheren Versionen der .NET Standard nicht verfügbar.Some types in the System.IO namespace, such as FileStream, are not available in earlier versions of the .NET Standard. Unity stellt jedoch die Verzeichnis-, Datei-und FileStream -Typen bereit, sodass Sie Sie in Ihrem Spiel verwenden können.However, Unity does provide the Directory, File, and FileStream types so you can use them in your game.

Alternativ können Sie die Windows. Storage -APIs verwenden, die nur für UWP-apps verfügbar sind.Alternatively, you can use the Windows.Storage APIs, which are only available to UWP apps. Diese APIs beschränken jedoch die APP auf das Schreiben in ihren spezifischen Speicher und gewähren keinen kostenlosen Zugriff auf das gesamte Dateisystem.However, these APIs restrict the app to writing to their specific storage, and do not give it free access to the entire file system. Weitere Informationen finden Sie unter Dateien, Ordner und Bibliotheken .See Files, folders, and libraries for more information.

Ein wichtiger Hinweis ist, dass die Close -Methode nur in .NET Standard 2,0 und höher verfügbar ist (obwohl Unity eine Erweiterungsmethode bereitstellt).One important note is that the Close method is only available in .NET Standard 2.0 and later (though Unity provides an extension method). Verwenden Sie stattdessen "verwerfen".Use Dispose instead.

ThreadingThreading

Einige Typen in den System. Threading -Namespaces, wie z. b. Thread Pool, sind in früheren Versionen der .NET Standard nicht verfügbar.Some types in the System.Threading namespaces, such as ThreadPool, are not available in earlier versions of the .NET Standard. In diesen Fällen können Sie das Windows.System verwenden. Stattdessen wird ein Threading-Namespace erstellt.In these cases, you can use the Windows.System.Threading namespace instead.

Im folgenden wird erläutert, wie Sie das Threading in einem Unity-Spiel handhaben können, indem Sie die Platt Form abhängige Kompilierung verwenden, um sowohl für UWP-als auch für nicht-UWPHere's how you could handle threading in a Unity game, using platform-dependent compilation to prepare for both UWP and non-UWP platforms:

private void UsingThreads()
{
#if NETFX_CORE
    Windows.System.Threading.ThreadPool.RunAsync(workItem => SomeMethod());
#else
    System.Threading.ThreadPool.QueueUserWorkItem(workItem => SomeMethod());
#endif
}

SicherheitSecurity

Ein Teil von " System. Security". * Namespaces, wie z. b . System. Security. Cryptography. X509Certificates, sind nicht verfügbar, wenn Sie ein Unity-Spiel für UWP erstellen.Some of the System.Security.* namespaces, such as System.Security.Cryptography.X509Certificates, are not available when you build a Unity game for UWP. In diesen Fällen verwenden Sie die Windows. Security. * APIs, die einen Großteil der gleichen Funktionalität abdecken.In these cases, use the Windows.Security.* APIs, which cover much of the same functionality.

Im folgenden Beispiel werden einfach die Zertifikate aus einem Zertifikat Speicher mit dem angegebenen Namen abgerufen:The following example simply gets the certificates from a certificate store with the given name:

private async void GetCertificatesAsync(string certStoreName)
    {
#if NETFX_CORE
        IReadOnlyList<Certificate> certs = await CertificateStores.FindAllAsync();
        IEnumerable<Certificate> myCerts = 
            certs.Where((certificate) => certificate.StoreName == certStoreName);
#else
        X509Store store = new X509Store(certStoreName, StoreLocation.CurrentUser);
        store.Open(OpenFlags.OpenExistingOnly);
        X509Certificate2Collection certs = store.Certificates;
#endif
    }

Weitere Informationen zur Verwendung der WinRT-Sicherheits-APIs finden Sie unter Sicherheit .See Security for more information about using the WinRT security APIs.

NetzwerkNetworking

Ein Teil des System . Netzwerks. * Namespaces, wie z . b. System .net. Mail, sind auch beim Aufbau eines Unity-Spiels für UWP nicht verfügbar.Some of the System.Net.* namespaces, such as System.Net.Mail, are also not available when building a Unity game for UWP. Verwenden Sie für die meisten dieser APIs das entsprechende Windows. Networking. * und Windows. Web. * WinRT-APIs, um eine ähnliche Funktionalität zu erhalten.For most of these APIs, use the corresponding Windows.Networking.* and Windows.Web.* WinRT APIs to get similar functionality. Weitere Informationen finden Sie unter Netzwerk-und Webdienste .See Networking and web services for more information.

Verwenden Sie im Fall von System .net. Mailden Windows. applicationmodel. Email- Namespace.In the case of System.Net.Mail, use the Windows.ApplicationModel.Email namespace. Weitere Informationen finden Sie unter e-Mail senden .See Send email for more information.

Weitere InformationenSee also