Introduzione di .NET NativeGetting Started with .NET Native

È possibile seguire le stesse procedure sia che si stia scrivendo una nuova app di Windows per Windows 10 sia che si stia migrando un'app di Windows Store esistente.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. Per creare un'app .NET Native.NET Native , seguire questa procedura:To create a .NET Native.NET Native app, follow these steps:

  1. Sviluppare un'app UWP (Universal Windows Platform) per Windows 10e testare le build di debug dell'app per verificarne il corretto funzionamento.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. Gestire la reflection aggiuntiva e l'uso della serializzazione.Handle additional reflection and serialization usage.

  3. Distribuire e testare le build di rilascio dell'app.Deploy and test the release builds of your app.

  4. Risolvere manualmente i metadati mancantie ripetere il passaggio 3 finché non vengono risolti tutti i problemi.Manually resolve missing metadata, and repeat step 3 until all issues are resolved.

Nota

Se si sta migrando un'app di Windows Store esistente a .NET Native.NET Native, consultare Migrazione dell'app di Windows Store a .NET Native.If you are migrating an existing Windows Store app to .NET Native.NET Native, be sure to review Migrating Your Windows Store App to .NET Native.

Passaggio 1: Sviluppare e testare le build di debug dell'app UWPStep 1: Develop and test debug builds of your UWP app

Per sviluppare una nuova app ed eseguire la migrazione di un'app esistente, si segue lo stesso processo usato per una qualsiasi app di Windows.Whether you are developing a new app or migrating an existing one, you follow the same process as for any Windows app.

  1. Creare un nuovo progetto UWP in Visual Studio usando il modello dell'app di Windows universale per Visual C# o Visual Basic.Create a new UWP project in Visual Studio by using the Universal Windows app template for Visual C# or Visual Basic. Per impostazione predefinita, tutte le applicazioni UWP sono destinate a CoreCLR e le relative build di rilascio vengono compilate usando la catena di strumenti .NET Native.By default, all UWP applications target the CoreCLR and their release builds are compiled by using the .NET Native tool chain.

  2. Sono presenti alcuni problemi noti di compatibilità tra i progetti di app UWP compilati con o senza la catena di strumenti .NET Native.Note that there are some known compatibility issues between compiling UWP app projects with the .NET Native tool chain and without it. Per altre informazioni, vedere la guida alla migrazione .Refer to the migration guide for more information.

Ora è possibile scrivere codice C# o Visual Basic rispetto alla superficie di attacco .NET Native.NET Native da eseguire nel sistema locale (o nel simulatore).You can now write C# or Visual Basic code against the .NET Native.NET Native surface area that runs on the local system (or in the simulator).

Importante

Quando si sviluppa l'app, annotare qualsiasi uso di serializzazione o reflection nel codice.As you develop your app, note any use of serialization or reflection in your code.

Per impostazione predefinita, le compilazioni di debug vengono compilate tramite JIT per consentirne la distribuzione rapida tramite F5, mentre le compilazioni di rilascio vengono compilate usando la tecnologia di precompilazione .NET Native.NET Native .By default, debug builds are JIT-compiled to enable rapid F5 deployment, while release builds are compiled by using the .NET Native.NET Native pre-compilation technology. Quindi, è necessario compilare e testare le build di debug dell'app per verificarne il normale funzionamento prima di compilarle con la catena di strumenti .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.

Passaggio 2: Gestire l'uso aggiuntivo della reflection e della serializzazioneStep 2: Handle additional reflection and serialization usage

Default.rd.xml, il file di direttive di runtime, aggiunto automaticamente al progetto al momento della creazione,A runtime directives file, Default.rd.xml, is automatically added to your project when you create it. si trova nella cartella Proprietà del progetto se si sviluppa in C#,If you develop in C#, it is found in your project's Properties folder. nella cartella Progetto personale del progetto se si sviluppa in Visual Basic.If you develop in Visual Basic, it is found in your project's My Project folder.

Nota

Per una panoramica del processo di compilazione di .NET Native e informazioni di base sui motivi per cui è necessario un file di direttive di runtime, vedere Compilazione e .NET Native.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.

Il file di direttive di runtime viene usato per definire i metadati necessari all'app in fase di esecuzione.The runtime directives file is used to define the metadata that your app needs at run time. In alcuni casi, la versione predefinita del file potrebbe essere sufficiente.In some cases, the default version of the file may be adequate. Tuttavia, il codice che si basa sulla serializzazione o la reflection potrebbe richiedere voci aggiuntive nei file di direttive di runtime.However, some code that relies on serialization or reflection may require additional entries in the runtime directives file.

SerializzazioneSerialization
Esistono due categorie di serializzatori ed entrambe possono richiedere voci aggiuntive nel file di direttive di runtime:There are two categories of serializers, and both may require additional entries in the runtime directives file:

  • Serializzatori non basati sulla reflection.Non-reflection based serializers. I serializzatori nella libreria di classi .NET Framework, ad esempio le classi DataContractSerializer, DataContractJsonSerializere XmlSerializer , non si basano sulla reflection.The serializers found in the .NET Framework class library, such as the DataContractSerializer, DataContractJsonSerializer, and XmlSerializer classes, do not rely on reflection. Tuttavia, richiedono che il codice venga generato in base all'oggetto da serializzare o deserializzare.However, they do require that code be generated based on the object to be serialized or deserialized. Per altre informazioni, vedere la sezione "Serializzatori Microsoft" in Serialization and Metadata.For more information, see the "Microsoft Serializers" section in Serialization and Metadata.

  • Serializzatori di terze parti.Third-party serializers. Le librerie di serializzazione di terze parti, la più nota delle quali è il serializzatore JSON di NewtonSoft, sono generalmente basate sulla reflection e richiedono delle voci nel file *.rd.xml per supportare la serializzazione e la deserializzazione degli oggetti.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. Per altre informazioni, vedere la sezione "Serializzatori di terze parti" in Serialization and Metadata.For more information, see the "Third-Party Serializers" section in Serialization and Metadata.

Metodi basati sulla reflectionMethods that rely on reflection
In alcuni casi, l'uso della reflection nel codice non è scontato.In some cases, the use of reflection in code is not obvious. Alcuni modelli di programmazione o API comuni non sono considerati parte dell'API di reflection ma si basano sulla reflection per una corretta esecuzioneSome common APIs or programming patterns aren't considered part of the reflection API but rely on reflection to execute successfully. Sono inclusi i seguenti metodi di creazione di un'istanza del tipo di costruzione del metodo:This includes the following type instantiation and method construction methods:

Per altre informazioni, vedere APIs That Rely on Reflection.For more information, see APIs That Rely on Reflection.

Nota

I nomi dei tipi usati nei file di direttive di runtime devono essere completi.Type names used in runtime directives files must be fully qualified. Ad esempio, il file deve specificare "System.String" invece di "String".For example, the file must specify "System.String" instead of "String".

Passaggio 3: Distribuire e testare le build di rilascio dell'appStep 3: Deploy and test the release builds of your app

Dopo aver aggiornato il file di direttive di runtime, è possibile ricompilare e distribuire le build di rilascio dell'app.After you’ve updated the runtime directives file, you can rebuild and deploy release builds of your app. I file binari di .NET Native vengono inseriti nella sottodirectory ILC.out della directory specificata nella casella di testo Percorso dell'output di compilazione della scheda Compila della finestra di dialogo Proprietà . I file binari non inclusi nella cartella non sono stati compilati con .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. Testare accuratamente l'app e tutti gli scenari, inclusi gli scenari di errore, in ogni piattaforma di destinazione.Test your app thoroughly, and test all scenarios, including failure scenarios, on each of its target platforms.

Se l'app non funziona correttamente (in particolare se genera eccezioni MissingMetadataException o MissingInteropDataException in runtime), seguire le istruzioni della sezione successiva Passaggio 4: Risolvere manualmente i metadati mancanti.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'abilitazione di eccezioni first-chance aiuta a individuare i bug.Enabling first-chance exceptions may help you find these bugs.

Dopo aver testato ed eseguito il debug delle build di debug dell'app e quando si è certi di aver eliminato le eccezioni MissingMetadataException e MissingInteropDataException , testare l'app come app ottimizzata per .NET Native.NET Native .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.NET Native app. Per eseguire questa operazione, modificare la configurazione del progetto attiva da Debug a Rilascio.To do this, change your active project configuration from Debug to Release.

Passaggio 4: Risolvere manualmente i metadati mancantiStep 4: Manually resolve missing metadata

L'errore più frequente in .NET Native.NET Native , ma inesistente nel desktop, è la generazione di un'eccezione MissingMetadataException, MissingInteropDataExceptiono MissingRuntimeArtifactException al runtime.The most common failure you'll encounter with .NET Native.NET Native that you don't encounter on the desktop is a runtime MissingMetadataException, MissingInteropDataException, or MissingRuntimeArtifactException exception. In alcuni casi, l'assenza di metadati può causare un comportamento imprevisto o anche errori dell'app.In some cases, the absence of metadata can manifest itself in unpredictable behavior or even in app failures. In questa sezione viene descritto come eseguire il debug e risolvere tali eccezioni aggiungendo delle direttive al file di direttive di runtime.This section discusses how you can debug and resolve these exceptions by adding directives to the runtime directives file. Per informazioni sul formato delle direttive di runtime, vedere Informazioni di riferimento sul file di configurazione delle direttive di runtime (rd.xml).For information about the format of runtime directives, see Runtime Directives (rd.xml) Configuration File Reference. Dopo aver aggiunto le direttive di runtime, distribuire e testare di nuovo l'app e risolvere eventuali nuove eccezioni MissingMetadataException, MissingInteropDataException e MissingRuntimeArtifactException finché non ne vengono più generate.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.

Suggerimento

Specificare le direttive di runtime a un alto livello per rendere l'app adattabile alle modifiche del codice.Specify the runtime directives at a high level to enable your app to be resilient to code changes. Si consiglia di aggiungere le direttive di runtime a livello degli spazi dei nomi e dei tipi e non a livello dei membri.We recommend adding runtime directives at the namespace and type levels rather than the member level. Potrebbe essere necessario un compromesso tra resilienza, file binari di grandi dimensioni e tempi di compilazione più lunghi.Note that there may be a tradeoff between resiliency and larger binaries with longer compile times.

Quando si risolve un'eccezione relativa a metadati mancanti, prendere in considerazione quanto segue:When addressing a missing metadata exception, consider these issues:

  • Che cosa stava tentando di eseguire l'app prima dell'eccezione?What was the app trying to do before the exception?

    • Ad esempio, stava eseguendo il data binding, la serializzazione o la deserializzazione dei dati o usando direttamente l'API reflection?For example, was it data binding, serializing or deserializing data, or directly using the reflection API?
  • Si tratta di un caso isolato o si ritiene che possa verificarsi lo stesso problema anche per altri tipi?Is this an isolated case, or do you believe you'll encounter the same issue for other types?

    • Ad esempio, un'eccezione MissingMetadataException viene generata durante la serializzazione di un tipo nel modello a oggetti dell'app.For example, a MissingMetadataException exception is thrown when serializing a type in the app’s object model. Se si conoscono gli altri tipi da serializzare, è possibile aggiungere contemporaneamente le direttive di runtime per questi tipi (o per gli spazi dei nomi che li contengono, a seconda di quanto efficacemente è organizzato il codice).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.
  • È possibile riscrivere il codice in modo che non usi la reflection?Can you rewrite the code so it doesn’t use reflection?

    • Ad esempio, il codice usa la parola chiave dynamic quando si conosce il tipo previsto?For example, does the code use the dynamic keyword when you know what type to expect?

    • Il codice chiama un metodo basato sulla reflection quando è disponibile un'alternativa migliore?Does the code call a method that depends on reflection when some better alternative is available?

Nota

Per altre informazioni sulla gestione dei problemi derivanti dalle differenze relative alla reflection e alla disponibilità dei metadati nelle app desktop e .NET Native.NET Native, vedere APIs That Rely on Reflection.For additional information about handling problems that stem from differences in reflection and the availability of metadata in desktop apps and .NET Native.NET Native, see APIs That Rely on Reflection.

Per alcuni esempi specifici di gestione delle eccezioni e di altri problemi relativi ai test dell'app, vedere:For some specific examples of handling exceptions and other issues that occur when testing your app, see:

Vedere ancheSee Also

Informazioni di riferimento sul file di configurazione delle direttive di runtime (rd.xml)Runtime Directives (rd.xml) Configuration File Reference
NIB: Installazione di .NET Native e configurazioneNIB: .NET Native Setup and Configuration
.NET Native e compilazione.NET Native and Compilation
Reflection e .NET NativeReflection and .NET Native
API basate sulla reflectionAPIs That Rely on Reflection
Serializzazione e metadatiSerialization and Metadata
Migrazione dell'app di Windows Store a .NET NativeMigrating Your Windows Store App to .NET Native