API .NET manquantes dans Unity et UWPMissing .NET APIs in Unity and UWP

Lors de la création d’un jeu UWP à l’aide de .NET, vous pouvez constater que certaines API que vous pouvez utiliser dans l’éditeur Unity ou pour un jeu PC autonome ne sont pas présentes pour UWP.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. Cela est dû au fait que .NET pour les applications UWP comprend un sous-ensemble des types fournis dans le .NET Framework complet pour chaque espace de noms.That's because .NET for UWP apps includes a subset of the types provided in the full .NET Framework for each namespace.

En outre, certains moteurs de jeu utilisent des versions différentes de .NET qui ne sont pas entièrement compatibles avec .NET pour UWP, telles que les mono de Unity.Additionally, some game engines use different flavors of .NET that aren't fully compatible with .NET for UWP, such as Unity's Mono. Ainsi, lorsque vous écrivez votre jeu, tout peut fonctionner correctement dans l’éditeur, mais lorsque vous vous rendez à la génération pour UWP, vous pouvez obtenir des erreurs telles que : le type ou l’espace de noms’Formatters’n’existe pas dans l’espace de noms’System. Runtime. Serialization' (une référence d’assembly est-elle manquante ?)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?)

Heureusement, Unity fournit certaines de ces API manquantes comme méthodes d’extension et types de remplacement, qui sont décrits dans plateforme Windows universelle : types .net manquants sur le serveur principal de script .net.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. Toutefois, si la fonctionnalité dont vous avez besoin n’est pas ici, la vue d’ensemble de .net pour les applications Windows 8. x explique comment vous pouvez convertir votre code pour utiliser WinRT ou .net pour les API Windows Runtime.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. (Il aborde Windows 8, mais s’applique également aux applications UWP Windows 10.)(It discusses Windows 8, but is applicable to Windows 10 UWP apps as well.)

.NET Standard.NET Standard

Pour comprendre pourquoi certaines API peuvent ne pas fonctionner, il est important de comprendre les différentes versions de .NET et la façon dont UWP met en œuvre .NET.To understand why some APIs might not be working, it's important to understand the different .NET flavors and how UWP implements .NET. Le .NET standard est une spécification formelle des API .net qui est censée être multiplateforme et unifier les différentes versions de .net.The .NET Standard is a formal specification of .NET APIs that is meant to be cross-platform, and unify the different .NET flavors. Chaque implémentation de .NET prend en charge une certaine version du .NET Standard.Each implementation of .NET supports a certain version of the .NET Standard. Vous pouvez consulter un tableau des normes et des implémentations au niveau de la prise en charge de l’implémentation .net.You can see a table of standards and implementations at .NET implementation support.

Chaque version du kit de développement logiciel (SDK) UWP est conforme à un autre niveau de .NET Standard.Each version of the UWP SDK conforms to a different level of .NET Standard. Par exemple, le kit de développement logiciel (SDK) 16299 (la mise à jour des créateurs de automne) prend en charge .NET Standard 2,0.For example, the 16299 SDK (the Fall Creators Update) supports .NET Standard 2.0.

Si vous souhaitez savoir si une certaine API .NET est prise en charge dans la version UWP que vous ciblez, vous pouvez vérifier la référence de l' api .NET standard et sélectionner la version du .NET standard qui est prise en charge par cette version de UWP.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.

Configuration du serveur principal de scriptScripting backend configuration

La première chose à faire si vous rencontrez des problèmes de génération pour UWP consiste à vérifier les paramètres du lecteur (fichiers > paramètres de Build, sélectionnez plateforme Windows universelle, puis paramètres du lecteur).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). Sous autres paramètres > la configuration, les trois premières listes déroulantes (Scripting Runtime, serveur principal de scriptet niveau de compatibilité d’API) sont tous des paramètres importants à prendre en compte.Under Other Settings > Configuration, the first three dropdowns (Scripting Runtime Version, Scripting Backend, and Api Compatibility Level) are all important settings to consider.

La version du runtime de script est celle utilisée par le backend de script Unity, qui vous permet d’acquérir la version équivalente (à peu près) de la prise en charge de .NET Framework que vous choisissez.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. Toutefois, gardez à l’esprit que toutes les API de cette version du .NET Framework ne seront pas prises en charge, mais uniquement celles de la version de .NET Standard que votre UWP cible.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.

Souvent, avec les nouvelles versions de .NET, d’autres API sont ajoutées à .NET Standard qui peuvent vous permettre d’utiliser le même code sur des plateformes autonomes et UWP.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. Par exemple, la System.Runtime.Serialization.Jssur l’espace de noms a été introduite dans .NET standard 2,0.For example, the System.Runtime.Serialization.Json namespace was introduced in .NET Standard 2.0. Si vous définissez la version du runtime de script sur .net 3,5 équivalent (qui cible une version antérieure du .NET standard), vous obtiendrez une erreur lors de la tentative d’utilisation de l’API. Passez à l' équivalent .net 4,6 (qui prend en charge .NET standard 2,0), et l’API fonctionnera.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.

Le serveur principal de script peut être .net ou IL2CPP.The Scripting Backend can be .NET or IL2CPP. Pour cette rubrique, nous supposons que vous avez choisi .net, car c’est là qu’interviennent les problèmes abordés ici.For this topic, we assume you have chosen .NET, since that's where the problems discussed here arise. Pour plus d’informations, consultez les serveurs principaux de script .See Scripting Backends for more information.

Enfin, vous devez définir le niveau de compatibilité de l’API sur la version de .net sur laquelle vous souhaitez que votre jeu s’exécute.Finally, you should set the Api Compatibility Level to the version of .NET that you want your game to run on. Cela doit correspondre à la version du runtime de script.This should match the Scripting Runtime Version.

En général, pour la version du runtime de script et le niveau de compatibilité de l' API, vous devez sélectionner la dernière version disponible afin de bénéficier d’une plus grande compatibilité avec le .NET Framework, et ainsi vous permettre d’utiliser davantage d’API .net.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.

Configuration : script de la version du Runtime ; Serveur principal de script ; Niveau de compatibilité de l’API

Compilation dépendante de la plateformePlatform-dependent compilation

Si vous créez votre jeu Unity pour plusieurs plateformes, y compris UWP, vous souhaiterez utiliser la compilation dépendante de la plateforme pour vous assurer que le code destiné à UWP est uniquement exécuté quand le jeu est créé en tant que UWP.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. De cette façon, vous pouvez utiliser la .NET Framework complète pour les plateformes bureau autonome et autres plateformes, et les API WinRT pour UWP, sans obtenir d’erreurs de génération.This way, you can use the full .NET Framework for standalone desktop and other platforms, and WinRT APIs for UWP, without getting build errors.

Utilisez les directives suivantes pour compiler uniquement le code lors de l’exécution en tant qu’application UWP :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

Notes

NETFX_CORE est conçu uniquement pour vérifier si vous compilez le code C# par rapport au serveur principal de script .NET.NETFX_CORE is only meant to check if you're compiling C# code against the .NET scripting backend. Si vous utilisez un autre serveur principal de script, tel que IL2CPP, utilisez à la ENABLE_WINMD_SUPPORT place.If you're using a different scripting backend, such as IL2CPP, use ENABLE_WINMD_SUPPORT instead.

Pour obtenir la liste complète des directives de compilation dépendant de la plateforme, consultez compilation dépendantde la plateforme.For the full list of platform-dependent compilation directives, see Platform dependent compilation.

Problèmes courants et solutions de contournementCommon issues and workarounds

Les scénarios suivants décrivent les problèmes courants qui peuvent survenir lorsque les API .NET sont absentes du sous-ensemble UWP et comment les contourner.The following scenarios describe common issues that might arise where .NET APIs are missing from the UWP subset, and ways to get around them.

Sérialisation de données à l’aide de BinaryFormatterData serialization using BinaryFormatter

Il est courant pour les jeux de sérialiser les données d’enregistrement afin que les joueurs ne puissent pas facilement les manipuler.It is common for games to serialize save data so that players can't easily manipulate it. Toutefois, BinaryFormatter, qui sérialise un objet en binaire, n’est pas disponible dans les versions antérieures du .NET standard (avant 2,0).However, BinaryFormatter, which serializes an object into binary, is not available in earlier versions of the .NET Standard (prior to 2.0). Envisagez plutôt d’utiliser XmlSerializer ou 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();
}

opérations d'E/SI/O operations

Certains types de l’espace de noms System.IO , tels que FileStream, ne sont pas disponibles dans les versions antérieures du .NET standard.Some types in the System.IO namespace, such as FileStream, are not available in earlier versions of the .NET Standard. Toutefois, Unity fournit les types de répertoire, de fichieret FileStream , ce qui vous permet de les utiliser dans votre jeu.However, Unity does provide the Directory, File, and FileStream types so you can use them in your game.

Vous pouvez également utiliser les API Windows. Storage , qui sont uniquement disponibles pour les applications UWP.Alternatively, you can use the Windows.Storage APIs, which are only available to UWP apps. Toutefois, ces API limitent l’accès de l’application à son stockage spécifique et ne lui offrent pas un accès gratuit à l’ensemble du système de fichiers.However, these APIs restrict the app to writing to their specific storage, and do not give it free access to the entire file system. Pour plus d’informations , consultez fichiers, dossiers et bibliothèques .See Files, folders, and libraries for more information.

Il est important de noter que la méthode Close est uniquement disponible dans .NET standard 2,0 et versions ultérieures (même si Unity fournit une méthode d’extension).One important note is that the Close method is only available in .NET Standard 2.0 and later (though Unity provides an extension method). Utilisez à la place dispose .Use Dispose instead.

ThreadsThreading

Certains types dans les espaces de noms System. Threading , tels que ThreadPool, ne sont pas disponibles dans les versions antérieures du .NET standard.Some types in the System.Threading namespaces, such as ThreadPool, are not available in earlier versions of the .NET Standard. Dans ce cas, vous pouvez utiliser le Windows.SysTEM. Espace de noms de thread à la place.In these cases, you can use the Windows.System.Threading namespace instead.

Voici comment vous pouvez gérer les threads dans un jeu Unity, en utilisant la compilation qui dépend de la plateforme pour préparer les plateformes UWP et non UWP :Here'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
}

SécuritéSecurity

Une partie de la System. Security. * les espaces de noms, tels que System. Security. Cryptography. X509Certificates, ne sont pas disponibles lorsque vous créez un jeu Unity pour UWP.Some of the System.Security.* namespaces, such as System.Security.Cryptography.X509Certificates, are not available when you build a Unity game for UWP. Dans ce cas, utilisez Windows. Security. * API, qui couvrent la plupart des fonctionnalités.In these cases, use the Windows.Security.* APIs, which cover much of the same functionality.

L’exemple suivant obtient simplement les certificats d’un magasin de certificats portant le nom donné :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
    }

Pour plus d’informations sur l’utilisation des API de sécurité WinRT, consultez sécurité .See Security for more information about using the WinRT security APIs.

Mise en réseauNetworking

Une partie du système . net. * les espaces de noms, tels que System .net. mail, ne sont pas non plus disponibles lors de la création d’un jeu Unity pour UWP.Some of the System.Net.* namespaces, such as System.Net.Mail, are also not available when building a Unity game for UWP. Pour la plupart de ces API, utilisez la mise en réseau Windows. Networking correspondante. * et Windows. Web. * API WinRT pour bénéficier d’une fonctionnalité similaire.For most of these APIs, use the corresponding Windows.Networking.* and Windows.Web.* WinRT APIs to get similar functionality. Pour plus d’informations, consultez mise en réseau et services Web .See Networking and web services for more information.

Dans le cas de System .net. mail, utilisez l’espace de noms Windows. ApplicationModel. email .In the case of System.Net.Mail, use the Windows.ApplicationModel.Email namespace. Pour plus d’informations, consultez Envoyer un message électronique .See Send email for more information.

Voir aussiSee also