Prise en main de .NET NativeGetting Started with .NET Native

Que vous écriviez une nouvelle application Windows pour Windows 10 ou que vous migriez une application du Windows Store existante, vous pouvez suivre le même ensemble de procédures.Whether you are writing a new Windows app for Windows 10 or you are migrating an existing Windows Store app, you can follow the same set of procedures. Pour créer une application .NET Native, procédez comme suit:To create a .NET Native app, follow these steps:

  1. Développez une application de la plateforme Windows universelle (UWP) qui cible Windows 10, puis testez les versions Debug de votre application pour vous assurer qu’elle fonctionne correctement.Develop a Universal Windows Platform (UWP) app that targets Windows 10, and test the debug builds of your app to ensure that it works properly.

  2. Gérez l'utilisation de réflexion et de sérialisation supplémentaire.Handle additional reflection and serialization usage.

  3. Déployez et testez les builds de mise en production de votre application.Deploy and test the release builds of your app.

  4. Résolvez manuellement les métadonnées manquantes et répétez l’étape 3 jusqu’à ce que tous les problèmes soient résolus.Manually resolve missing metadata, and repeat step 3 until all issues are resolved.

Notes

Si vous migrez une application du Windows Store existante vers .NET Native, veillez à passer en revue la rubrique migration de votre application du Windows Store vers .net Native.If you are migrating an existing Windows Store app to .NET Native, be sure to review Migrating Your Windows Store App to .NET Native.

Étape 1 : Développer et tester les versions Debug de votre application UWPStep 1: Develop and test debug builds of your UWP app

Que vous développiez une nouvelle application ou que vous migriez une application existante, vous devez suivre la même procédure que pour n'importe quelle application Windows.Whether you are developing a new app or migrating an existing one, you follow the same process as for any Windows app.

  1. Créez un nouveau projet UWP dans Visual Studio à l’aide du modèle d’application Windows universelle pour Visual C# ou Visual Basic.Create a new UWP project in Visual Studio by using the Universal Windows app template for Visual C# or Visual Basic. Par défaut, toutes les applications UWP ciblent CoreCLR et leurs versions de mise en production sont compilées à l’aide de la chaîne de l’outil .NET Native.By default, all UWP applications target the CoreCLR and their release builds are compiled by using the .NET Native tool chain.

  2. Notez qu’il existe certains problèmes de compatibilité connus entre la compilation des projets d’application UWP avec la chaîne de l’outil .NET Native et sans elle.Note that there are some known compatibility issues between compiling UWP app projects with the .NET Native tool chain and without it. Pour plus d'informations, consultez le guide de migration .Refer to the migration guide for more information.

Vous pouvez maintenant écrire C# ou Visual Basic code dans la surface d’exposition .net native qui s’exécute sur le système local (ou dans le simulateur).You can now write C# or Visual Basic code against the .NET Native surface area that runs on the local system (or in the simulator).

Important

Quand vous développez votre application, notez toute utilisation de la sérialisation ou de la réflexion dans votre code.As you develop your app, note any use of serialization or reflection in your code.

Par défaut, les builds de débogage sont compilées juste-à-temps pour permettre un déploiement F5 rapide, tandis que les versions release sont compilées à l’aide de la technologie de précompilation .NET Native.By default, debug builds are JIT-compiled to enable rapid F5 deployment, while release builds are compiled by using the .NET Native pre-compilation technology. Cela signifie que vous devez générer et tester les versions Debug de votre application pour vous assurer qu’elles fonctionnent normalement avant de les compiler avec la chaîne de l’outil .NET Native.This means you should build and test the debug builds of your app to ensure that they work normally before compiling them with the .NET Native tool chain.

Étape 2 : Gérer une réflexion et une utilisation de sérialisation supplémentairesStep 2: Handle additional reflection and serialization usage

Un fichier de directives runtime, Default.rd.xml, est automatiquement ajouté à votre projet au moment de sa création.A runtime directives file, Default.rd.xml, is automatically added to your project when you create it. Si vous développez en C#, il se trouve dans le dossier Propriétés de votre projet.If you develop in C#, it is found in your project's Properties folder. Si vous développez en Visual Basic, il se trouve dans le dossier Mon projet de votre projet.If you develop in Visual Basic, it is found in your project's My Project folder.

Notes

Pour une vue d'ensemble du processus de compilation .NET Native apportant des informations générales sur la nécessité d'un fichier de directives de runtime, voir .NET Native et compilation.For an overview of the .NET Native compilation process that provides background on why a runtime directives file is needed, see .NET Native and Compilation.

Le fichier de directives runtime permet de définir les métadonnées dont a besoin votre application au moment de l'exécution.The runtime directives file is used to define the metadata that your app needs at run time. Dans certains cas, la version par défaut du fichier peut convenir.In some cases, the default version of the file may be adequate. Toutefois, un code qui s’appuie sur la sérialisation ou la réflexion peut nécessiter des entrées supplémentaires dans le fichier de directives runtime.However, some code that relies on serialization or reflection may require additional entries in the runtime directives file.

SérialisationSerialization

Il existe deux catégories de sérialiseurs, et les deux peuvent nécessiter des entrées supplémentaires dans le fichier de directives runtime :There are two categories of serializers, and both may require additional entries in the runtime directives file:

  • Sérialiseurs non basés sur la réflexion.Non-reflection based serializers. Les sérialiseurs qui se trouvent dans la bibliothèque de classes .NET Framework, tels que les classes DataContractSerializer, DataContractJsonSerializer, and XmlSerializer , ne reposent pas sur la réflexion.The serializers found in the .NET Framework class library, such as the DataContractSerializer, DataContractJsonSerializer, and XmlSerializer classes, do not rely on reflection. Toutefois, ils nécessitent que du code soit généré en fonction de l'objet à sérialiser ou à désérialiser.However, they do require that code be generated based on the object to be serialized or deserialized. Pour plus d’informations, consultez la section « Sérialiseurs Microsoft » dans Serialization and Metadata.For more information, see the "Microsoft Serializers" section in Serialization and Metadata.

  • Sérialiseurs tiers.Third-party serializers. Les bibliothèques de sérialisation tierces, dont la plus courante est le sérialiseur JSON Newtonsoft, sont généralement basées sur la réflexion et nécessitent des entrées dans *le fichier. rd. xml pour prendre en charge la sérialisation et la désérialisation d’objets.Third-party serialization libraries, the most common of which is the Newtonsoft JSON serializer, are generally reflection-based and require entries in the *.rd.xml file to support object serialization and deserialization. Pour plus d’informations, consultez la section « Sérialiseurs tiers » dans Serialization and Metadata.For more information, see the "Third-Party Serializers" section in Serialization and Metadata.

Méthodes basées sur la réflexionMethods that rely on reflection

Dans certains cas, l'utilisation de la réflexion dans le code n'est pas évidente.In some cases, the use of reflection in code is not obvious. Certains modèles de programmation ou API courants ne sont pas considérés comme faisant partie de l'API de réflexion, mais s'appuient sur la réflexion pour s'exécuter correctement.Some common APIs or programming patterns aren't considered part of the reflection API but rely on reflection to execute successfully. Cela comprend les méthodes d'instanciation de type et de construction de méthode suivantes :This includes the following type instantiation and method construction methods:

Pour plus d'informations, consultez APIs That Rely on Reflection.For more information, see APIs That Rely on Reflection.

Notes

Les noms de types utilisés dans les fichiers de directives runtime doivent être qualifiés complets.Type names used in runtime directives files must be fully qualified. Par exemple, le fichier doit spécifier « System.String » au lieu de « String ».For example, the file must specify "System.String" instead of "String".

Étape 3 : Déployer et tester les versions release de votre applicationStep 3: Deploy and test the release builds of your app

Une fois que vous avez mis à jour le fichier de directives runtime, vous pouvez régénérer et déployer les versions de mise en production de votre application.After you’ve updated the runtime directives file, you can rebuild and deploy release builds of your app. Les fichiers binaires .NET Native sont placés dans le sous-répertoire ILC.out du répertoire spécifié dans la zone de texte Chemin de sortie de la génération de la boîte de dialogue Propriétés du projet, sous l'onglet Compiler . Les fichiers binaires qui ne figurent pas dans ce dossier n'ont pas été compilés avec .NET Native..NET Native binaries are placed in the ILC.out subdirectory of the directory specified in the Build output path text box of the project's Properties dialog box, Compile tab. Binaries that aren't in this folder haven't been compiled with .NET Native. Testez votre application minutieusement et testez tous les scénarios, y compris les scénarios d’erreur, sur chacune de ses plateformes cibles.Test your app thoroughly, and test all scenarios, including failure scenarios, on each of its target platforms.

Si votre application ne fonctionne pas correctement (en particulier dans les cas où elle lève des exceptions MissingMetadataException ou MissingInteropDataException au moment de l’exécution), suivez les instructions de la section suivante, étape 4: Résolvez manuellement lesmétadonnées manquantes.If your app doesn’t work properly (particularly in cases where it throws MissingMetadataException or MissingInteropDataException exceptions at run time), follow the instructions in the next section, Step 4: Manually resolve missing metadata. L'activation des exceptions de première chance peut vous aider à trouver ces bogues.Enabling first-chance exceptions may help you find these bugs.

Une fois que vous avez testé et débogué les versions Debug de votre application et que vous êtes certain d’avoir éliminé les exceptions MissingMetadataException et MissingInteropDataException , vous devez tester votre application en tant qu’application .net Native optimisée.When you’ve tested and debugged the debug builds of your app and you’re confident that you’ve eliminated the MissingMetadataException and MissingInteropDataException exceptions, you should test your app as an optimized .NET Native app. Pour ce faire, dans la configuration du projet actif, remplacez Débogage par Version finale.To do this, change your active project configuration from Debug to Release.

Étape 4 : Résoudre manuellement les métadonnées manquantesStep 4: Manually resolve missing metadata

La défaillance la plus courante que vous rencontrerez avec .NET Native que vous ne rencontrez pas sur le bureau est une exception Runtime MissingMetadataException, MissingInteropDataExceptionou MissingRuntimeArtifactException .The most common failure you'll encounter with .NET Native that you don't encounter on the desktop is a runtime MissingMetadataException, MissingInteropDataException, or MissingRuntimeArtifactException exception. Dans certains cas, l'absence de métadonnées peut se manifester par un comportement imprévisible ou même se traduire par des erreurs d'application.In some cases, the absence of metadata can manifest itself in unpredictable behavior or even in app failures. Cette section explique comment vous pouvez déboguer et résoudre ces exceptions en ajoutant des directives au fichier de directives runtime.This section discusses how you can debug and resolve these exceptions by adding directives to the runtime directives file. Pour plus d’informations sur le format des directives runtime, consultez le Guide de référence du fichier de configuration des directives runtime (rd.xml).For information about the format of runtime directives, see Runtime Directives (rd.xml) Configuration File Reference. Après avoir ajouté les directives runtime, vous devez déployer et tester votre application de nouveau et résoudre toute nouvelle exception MissingMetadataException, MissingInteropDataException et MissingRuntimeArtifactException jusqu’à ce qu’aucune exception ne soit levée.After you’ve added runtime directives, you should deploy and test your app again and resolve any new MissingMetadataException, MissingInteropDataException, and MissingRuntimeArtifactException exceptions until you encounter no more exceptions.

Conseil

Spécifiez les directives runtime à un niveau élevé pour que votre application tolère les modifications de code.Specify the runtime directives at a high level to enable your app to be resilient to code changes. Nous vous recommandons d'ajouter les directives runtime aux niveaux de l'espace de noms et du type, plutôt qu'au niveau du membre.We recommend adding runtime directives at the namespace and type levels rather than the member level. Notez qu'un compromis peut s'avérer nécessaire entre la résilience et les fichiers binaires volumineux dont la compilation prend plus de temps.Note that there may be a tradeoff between resiliency and larger binaries with longer compile times.

Quand vous traitez une exception liée à des métadonnées manquantes, prenez en compte les points suivants :When addressing a missing metadata exception, consider these issues:

  • Qu'est-ce que l'application essayait de faire avant l'exception ?What was the app trying to do before the exception?

    • Par exemple, était-elle en train de lier, de sérialiser ou de désérialiser des données ou d'utiliser directement l'API de réflexion ?For example, was it data binding, serializing or deserializing data, or directly using the reflection API?
  • S'agit-il d'un cas isolé, ou pensez-vous que vous rencontrerez le même problème pour d'autres types ?Is this an isolated case, or do you believe you'll encounter the same issue for other types?

    • Par exemple, une exception MissingMetadataException est levée pendant la sérialisation d'un type dans le modèle objet de l'application.For example, a MissingMetadataException exception is thrown when serializing a type in the app’s object model. Si vous connaissez d'autres types à sérialiser, vous pouvez ajouter des directives runtime pour ces types (ou pour leurs espaces de noms conteneurs, suivant la façon dont le code est organisé) en même temps.If you know other types that will be serialized, you can add runtime directives for those types (or for their containing namespaces, depending on how well the code is organized) at the same time.
  • Pouvez-vous réécrire le code afin qu'il n'utilise pas la réflexion ?Can you rewrite the code so it doesn’t use reflection?

    • Par exemple, le code utilise-t-il le mot clé dynamic quand vous connaissez le type attendu ?For example, does the code use the dynamic keyword when you know what type to expect?

    • Le code appelle-t-il une méthode basée sur la réflexion quand une meilleure solution est disponible ?Does the code call a method that depends on reflection when some better alternative is available?

Notes

Pour plus d’informations sur la gestion des problèmes qui résultent des différences de réflexion et de la disponibilité des métadonnées dans les applications de bureau et les .NET Native, consultez API qui reposent sur la réflexion.For additional information about handling problems that stem from differences in reflection and the availability of metadata in desktop apps and .NET Native, see APIs That Rely on Reflection.

Pour obtenir des exemples spécifiques de gestion des exceptions et d'autres problèmes qui se produisent quand vous testez votre application, consultez :For some specific examples of handling exceptions and other issues that occur when testing your app, see:

Voir aussiSee also