Utilisation de .NET 4.x dans Unity
C# et .NET, les technologies sur lesquelles reposent les scripts Unity, ont continué à être mises à jour depuis que Microsoft les a initialement lancées en 2002. Toutefois, les développeurs Unity ne sont peut-être pas conscients du flux régulier de nouvelles fonctionnalités ajoutées au langage C# et à .NET Framework, car avant Unity 2017.1, Unity utilisait un runtime de script équivalent .NET 3.5, qui manquait des années de mises à jour.
Avec la sortie d’Unity 2017.1, Unity a introduit une version expérimentale de son runtime de script, mise à niveau vers une version compatible avec .NET 4.6, C# 6.0. Dans Unity 2018.1, le runtime équivalent à .NET 4.x n’est plus considéré comme expérimental, alors que l’ancien runtime équivalent à .NET 3.5 est désormais considéré comme la version héritée. Avec la sortie d’Unity 2018.3, Unity prévoit de faire du runtime de script mis à niveau la sélection par défaut, et d’aller même encore plus loin en proposant une mise à jour pour le rendre compatible avec C# 7. Pour plus d’informations et pour obtenir les dernières mises à jour sur cette feuille de route, lisez le billet de blog consacré à Unity, ou visitez le forum des préversions de fonctionnalités de script expérimentales. En attendant, consultez les sections ci-dessous pour en savoir plus sur les nouvelles fonctionnalités disponibles dès maintenant avec le runtime de script .NET 4.x.
Prérequis
- Unity 2022.2 ou version ultérieure (2022.1.7 recommandé)
- Visual Studio 2019
Activation du runtime de script .NET 4.x dans Unity
Pour activer le runtime de script .NET 4.x, effectuez les étapes suivantes :
Ouvrez PlayerSettings dans l’inspecteur Unity en sélectionnant Modifier > Paramètres de projet > Lecteur > Autress paramètres.
Sous le titre Configuration, cliquez sur la liste déroulante Niveau de compatibilité de l’API, puis sélectionnez .NET Framework. Vous serez invité à redémarrer Unity.
Choix entre les profils .NET 4.x et .NET Standard 2.1
Une fois que vous êtes passé au runtime de script équivalent à .NET 4.x, vous pouvez spécifier le niveau de compatibilité d’API dans le menu déroulant de PlayerSettings (Modifier> Paramètres du projet > Lecteur). Nous avons deux options :
.NET Standard 2.1. Ce profil correspond au profil .NET Standard 2.1 publié par .NET Foundation. Unity recommande .NET Standard 2.1 pour les nouveaux projets. Il est plus petit que .NET 4.x, ce qui est avantageux pour les plateformes limitées en taille. De plus, Unity s’est engagé à prendre en charge ce profil sur toutes les plateformes prises en charge par Unity.
.NET Framework. Ce profil permet d’accéder à la dernière API .NET 4. Il inclut tout le code disponible dans les bibliothèques de classes .NET Framework et prend également en charge les profils .NET Standard 2.1. Utilisez le profil .NET 4.x si votre projet nécessite une partie de l’API non incluse dans le profil .NET Standard 2.0. Toutefois, certaines parties de cette API ne sont peut-être pas prises en charge sur toutes les plateformes d’Unity.
Pour en savoir plus sur ces options dans Unity, lisez le billet de blog.
Ajout de références d’assembly en cas d’utilisation du niveau de compatibilité d’API .NET 4.x
Quand vous utilisez le paramètre .NET Standard 2.1 de la liste déroulante Niveau de compatibilité d’API, tous les assemblys du profil d’API sont référencés et utilisables. Toutefois, quand vous utilisez le profil .NET 4.x, qui est plus conséquent, certains des assemblys expédiés avec Unity, ne sont pas référencés par défaut. Pour utiliser ces API, vous devez ajouter manuellement une référence d’assembly. Vous pouvez voir quels sont les assemblys avec lesquels Unity est livré dans le répertoire MonoBleedingEdge/lib/mono de votre installation de l’éditeur Unity :
Par exemple, si vous utilisez le profil .NET 4.x et si vous souhaitez utiliser HttpClient, vous devez ajouter une référence d’assembly pour System.Net.Http.dll. Sinon, le compilateur signale l’absence d’une référence d’assembly :
Visual Studio regénère les fichiers ..csproj et .sln des projets Unity chaque fois qu’ils sont ouverts. Ainsi, vous ne pouvez pas ajouter de références d’assembly directement dans Visual Studio, car elles sont perdues à la réouverture du projet. À la place, vous devez utiliser un fichier texte spécial nommé csc.rsp :
Créez un fichier texte nommé csc.rsp dans le répertoire Assets racine de votre projet Unity.
Sur la première ligne du fichier texte vide, entrez
-r:System.Net.Http.dll, puis enregistrez le fichier. Vous pouvez remplacer « System.Net.Http.dll » par n’importe quel assembly inclus auquel il peut manquer une référence.Redémarrez l’éditeur Unity.
Tirer parti de la compatibilité .NET
En plus des nouvelles fonctionnalités de syntaxe et de langage C#, le runtime de script .NET 4.x permet aux utilisateurs d’Unity d’accéder à une vaste bibliothèque de packages .NET incompatibles avec le runtime de script .NET 3.5 existant.
Ajouter des packages NuGet à un projet Unity
NuGet est le gestionnaire de package pour .NET. NuGet est intégré à Visual Studio. Toutefois, les projets Unity nécessitent un processus spécial pour ajouter des packages NuGet, car lorsque vous ouvrez un projet dans Unity, ses fichiers projet Visual Studio sont régénérés, annulant ainsi les configurations nécessaires. Pour ajouter un package NuGet à votre projet Unity :
Parcourez NuGet pour localiser un package compatible à ajouter (.NET Standard 2.0 ou .NET 4.x). Cet exemple montre comment ajouter Json.NET (package souvent utilisé avec JSON) à un projet .NET Standard 2.0.
Cliquez sur le bouton Télécharger :
Localisez le fichier téléchargé, puis remplacez l’extension .nupkg par .zip.
Dans le fichier zip, accédez au répertoire lib/netstandard2.0, puis copiez le fichier Newtonsoft.Json.dll.
Dans le dossier Assets racine de votre projet Unity, créez un dossier nommé Plugins. Plugins est un nom de dossier spécial dans Unity. Pour plus d’informations, consultez la documentation relative à Unity.
Collez le fichier Newtonsoft.Json.dll dans le répertoire Plugins de votre projet Unity.
Créez un fichier nommé link.xml dans le répertoire Assets de votre projet Unity et ajoutez le code XML suivant, en veillant à ce que le processus de suppression de bytecode d’Unity ne supprime pas les données nécessaires lors de l’exportation vers une plateforme IL2CPP. Bien que cette étape soit spécifique à cette bibliothèque, vous pouvez rencontrer des problèmes avec d’autres bibliothèques qui utilisent Reflection de manière similaire. Pour plus d’informations, consultez la documentation d’Unity dans cet article.
<linker> <assembly fullname="System.Core"> <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" /> </assembly> </linker>
Tout étant en place, vous pouvez désormais utiliser le package Json.NET.
using Newtonsoft.Json;
using UnityEngine;
public class JSONTest : MonoBehaviour
{
class Enemy
{
public string Name { get; set; }
public int AttackDamage { get; set; }
public int MaxHealth { get; set; }
}
private void Start()
{
string json = @"{
'Name': 'Ninja',
'AttackDamage': '40'
}";
var enemy = JsonConvert.DeserializeObject<Enemy>(json);
Debug.Log($"{enemy.Name} deals {enemy.AttackDamage} damage.");
// Output:
// Ninja deals 40 damage.
}
}
Ceci est un exemple simple d’utilisation d’une bibliothèque qui n’a aucune dépendance. Quand les packages NuGet reposent sur d’autres packages NuGet, vous devez télécharger ces dépendances manuellement et les ajouter au projet de la même manière.
Nouvelles fonctionnalités de syntaxe et de langage
L’utilisation du runtime de script mis à jour permet aux développeurs Unity d’accéder à C# 8 et à une multitude de nouvelles fonctionnalités de syntaxe et de langage.
Initialiseurs de propriétés automatiques
Dans le runtime de script .NET 3.5 d’Unity, la syntaxe des propriétés automatiques permet de définir facilement et rapidement les propriétés non initialisées. Toutefois, l’initialisation doit avoir lieu ailleurs dans votre script. Désormais, avec le runtime .NET 4.x, il est possible d’initialiser les propriétés automatiques sur la même ligne :
// .NET 3.5
public int Health { get; set; } // Health has to be initialized somewhere else, like Start()
// .NET 4.x
public int Health { get; set; } = 100;
Interpolation de chaîne
Avec l’ancien runtime .NET 3.5, la concaténation de chaînes nécessitait une syntaxe compliquée. Désormais, avec le runtime .NET 4.x et grâce à , la fonctionnalité d’$interpolation de chaînes, vous pouvez insérer des expressions dans des chaînes à l’aide d’une syntaxe plus directe et plus lisible :
// .NET 3.5
Debug.Log(String.Format("Player health: {0}", Health)); // or
Debug.Log("Player health: " + Health);
// .NET 4.x
Debug.Log($"Player health: {Health}");
Membres expression-bodied
Avec la nouvelle syntaxe C# disponible dans le runtime .NET 4.x, les expressions lambda peuvent remplacer le corps des fonctions pour les rendre plus succinctes :
// .NET 3.5
private int TakeDamage(int amount)
{
return Health -= amount;
}
// .NET 4.x
private int TakeDamage(int amount) => Health -= amount;
Vous pouvez également utiliser des membres expression-bodied dans des propriétés en lecture seule :
// .NET 4.x
public string PlayerHealthUiText => $"Player health: {Health}";
Modèle asynchrone basé sur les tâches (TAP, Task-based Asynchronous Pattern)
La programmation asynchrone permet d’effectuer des opérations longues sans entraîner d’absence de réponse de la part de votre application. Cette fonctionnalité permet également à votre code d’attendre la fin des opérations longues avant de poursuivre l’exécution de tout autre code dépendant des résultats de ces opérations. Par exemple, vous pouvez attendre la fin du chargement d’un fichier ou d’une opération réseau.
Dans Unity, vous effectuez généralement la programmation asynchrone à l’aide de coroutines. Toutefois, depuis C# 5, la méthode de programmation asynchrone préférée pour le développement .NET est le modèle TAP (modèle asynchrone basé sur les tâches) à l’aide des mots clés async et await avec System.Threading.Task. En résumé, dans une fonction async, vous pouvez appliquer await à l’exécution d’une tâche sans bloquer la mise à jour du reste de votre application :
// Unity coroutine
using UnityEngine;
public class UnityCoroutineExample : MonoBehaviour
{
private void Start()
{
StartCoroutine(WaitOneSecond());
DoMoreStuff(); // This executes without waiting for WaitOneSecond
}
private IEnumerator WaitOneSecond()
{
yield return new WaitForSeconds(1.0f);
Debug.Log("Finished waiting.");
}
}
// .NET 4.x async-await
using UnityEngine;
using System.Threading.Tasks;
public class AsyncAwaitExample : MonoBehaviour
{
private async void Start()
{
Debug.Log("Wait.");
await WaitOneSecondAsync();
DoMoreStuff(); // Will not execute until WaitOneSecond has completed
}
private async Task WaitOneSecondAsync()
{
await Task.Delay(TimeSpan.FromSeconds(1));
Debug.Log("Finished waiting.");
}
}
TAP est un sujet complexe, avec des nuances spécifiques à Unity dont les développeurs doivent tenir compte. TAP n’est donc pas un remplacement universel des coroutines dans Unity. Toutefois, il s’agit d’un outil parmi d’autres à utiliser. La portée de cette fonctionnalité dépasse le cadre de cet article, mais certaines bonnes pratiques et astuces générales sont fournies ci-dessous.
Informations de référence pour bien démarrer avec TAP dans Unity
Ces conseils peuvent vous aider à bien démarrer avec TAP dans Unity :
- Les fonctions asynchrones destinées à être attendues doivent avoir le type de retour
TaskouTask<TResult>. - Les fonctions asynchrones qui retournent une tâche doivent avoir le suffixe « Async » accolé à leurs noms. Le suffixe « Async » permet d’indiquer qu’une fonction doit toujours être attendue.
- Utilisez uniquement le type de retour
async voidpour les fonctions qui déclenchent des fonctions asynchrones à partir du code synchrone classique. De telles fonctions ne peuvent pas être attendues et ne doivent pas comporter le suffixe « Async » dans leurs noms. - Unity utilise UnitySynchronizationContext pour garantir l’exécution des fonctions asynchrones sur le thread principal par défaut. L’API Unity n’est pas accessible en dehors du thread principal.
- Il est possible d’exécuter des tâches sur les threads d’arrière-plan avec des méthodes telles que
Task.RunetTask.ConfigureAwait(false). Cette technique permet de décharger les opérations coûteuses du thread principal pour améliorer les performances. Toutefois, l’utilisation de threads d’arrière-plan peut entraîner des problèmes difficiles à déboguer, par exemple les conditions de concurrence. - L’API Unity n’est pas accessible en dehors du thread principal.
- Les tâches qui utilisent des threads ne sont pas prises en charge sur les builds Unity WebGL.
Différences entre coroutines et TAP
Il existe des différences importantes entre les coroutines et TAP/async-await :
- Les coroutines ne peuvent pas retourner de valeurs, contrairement à
Task<TResult>. - Vous ne pouvez pas mettre
yielddans une instruction try-catch, ce qui complique les erreurs de gestion avec les coroutines. Toutefois, try-catch fonctionne avec TAP. - La fonctionnalité de coroutine d’Unity n’est pas disponible dans les classes qui ne dérivent pas de MonoBehaviour. TAP est idéal pour la programmation asynchrone dans de telles classes.
- À ce stade, Unity ne suggère pas d’utiliser TAP en tant que remplacement systématique des coroutines. Le profilage est le seul moyen de connaître les résultats spécifiques d’une approche par rapport à l’autre pour un projet donné.
opérateur nameof
L’opérateur nameof obtient le nom de chaîne d’une variable, d’un type ou d’un membre. Dans certains cas, nameof est utile, par exemple pour journaliser les erreurs et obtenir le nom de chaîne d’un enum :
// Get the string name of an enum:
enum Difficulty {Easy, Medium, Hard};
private void Start()
{
Debug.Log(nameof(Difficulty.Easy));
RecordHighScore("John");
// Output:
// Easy
// playerName
}
// Validate parameter:
private void RecordHighScore(string playerName)
{
Debug.Log(nameof(playerName));
if (playerName == null) throw new ArgumentNullException(nameof(playerName));
}
Attributs d’informations de l’appelant
Les attributs d’informations de l’appelant fournissent des informations sur l’appelant d’une méthode. Vous devez fournir une valeur par défaut pour chaque paramètre à utiliser avec un attribut d’informations de l’appelant :
private void Start ()
{
ShowCallerInfo("Something happened.");
}
public void ShowCallerInfo(string message,
[System.Runtime.CompilerServices.CallerMemberName] string memberName = "",
[System.Runtime.CompilerServices.CallerFilePath] string sourceFilePath = "",
[System.Runtime.CompilerServices.CallerLineNumber] int sourceLineNumber = 0)
{
Debug.Log($"message: {message}");
Debug.Log($"member name: {memberName}");
Debug.Log($"source file path: {sourceFilePath}");
Debug.Log($"source line number: {sourceLineNumber}");
}
// Output:
// Something happened
// member name: Start
// source file path: D:\Documents\unity-scripting-upgrade\Unity Project\Assets\CallerInfoTest.cs
// source line number: 10
Using static
Using static vous permet d’utiliser des fonctions statiques sans taper leur nom de classe. Avec using static, vous pouvez gagner de la place et du temps si vous devez utiliser plusieurs fonctions statiques provenant de la même classe :
// .NET 3.5
using UnityEngine;
public class Example : MonoBehaviour
{
private void Start ()
{
Debug.Log(Mathf.RoundToInt(Mathf.PI));
// Output:
// 3
}
}
// .NET 4.x
using UnityEngine;
using static UnityEngine.Mathf;
public class UsingStaticExample: MonoBehaviour
{
private void Start ()
{
Debug.Log(RoundToInt(PI));
// Output:
// 3
}
}
Considérations relatives à IL2CPP
Quand vous exportez votre jeu sur des plateformes comme iOS, Unity utilise son moteur IL2CPP pour « transpiler » le code IL en code C++, lequel est ensuite compilé à l’aide du compilateur natif de la plateforme cible. Dans ce scénario, plusieurs fonctionnalités .NET ne sont pas prises en charge, par exemple certaines parties de Reflection et l’utilisation du mot clé dynamic. Bien que vous puissiez contrôler l’utilisation de ces fonctionnalités dans votre propre code, vous pouvez rencontrer des problèmes dans les DLL et kits SDK tiers qui n’ont pas été écrits en tenant compte des spécificités d’Unity et d’IL2CPP. Pour plus d’informations dans cet article, consultez la documentation sur les restrictions relatives aux scripts sur le site d’Unity.
De plus, comme indiqué dans l’exemple Json.NET ci-dessus, Unity tente de supprimer le code inutilisé durant le processus d’exportation IL2CPP. Bien que ce processus ne pose généralement pas de problème, les bibliothèques qui utilisent Reflection peuvent accidentellement supprimer des propriétés ou des méthodes appelées au moment de l’exécution, et qui ne peuvent pas être déterminées au moment de l’exportation. Pour résoudre ces problèmes, ajoutez un fichier link.xml au projet qui contient une liste d’assemblys et d’espaces de noms sur lesquels le processus de suppression ne doit pas s’exécuter. Pour plus d’informations, consultez la documentation d’Unity sur la suppression du bytecode.
Exemple de projet Unity .NET 4.x
Il s’agit d’exemples d’utilisation de plusieurs fonctionnalités .NET 4.x. Vous pouvez télécharger le projet ou voir le code source sur GitHub.
Ressources supplémentaires
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour