Introducción a .NET NativeGetting Started with .NET Native

El conjunto de procedimientos que se debe seguir es el mismo, independientemente de si está creando una nueva aplicación de Windows para Windows 10 o si está migrando una aplicación que ya existe en la Tienda Windows.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. Para crear una aplicación .NET Native, siga estos pasos:To create a .NET Native app, follow these steps:

  1. Desarrolle una aplicación de plataforma universal de Windows (UWP) destinada a Windows 10y pruebe la aplicación para asegurarse de que funciona correctamente.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. Administre el uso de reflexión y serialización adicionales.Handle additional reflection and serialization usage.

  3. Implemente y pruebe las compilaciones de lanzamiento de la aplicación.Deploy and test the release builds of your app.

  4. Resuelva manualmente los metadatos que faltan y repita el paso 3 hasta que todos los problemas estén solucionados.Manually resolve missing metadata, and repeat step 3 until all issues are resolved.

Nota

Si va a migrar una aplicación de la tienda Windows existente a .NET Native, asegúrese de revisar la migración de la aplicación de la tienda Windows a .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.

Paso 1: desarrollar y probar compilaciones de depuración de la aplicación de UWPStep 1: Develop and test debug builds of your UWP app

Tanto si va a desarrollar una nueva aplicación o migrar una ya existente, el procedimiento es el mismo para cualquier aplicación de Windows.Whether you are developing a new app or migrating an existing one, you follow the same process as for any Windows app.

  1. Crear un nuevo proyecto de UWP en Visual Studio mediante la plantilla de aplicación universal de Windows para 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. De forma predeterminada, todas las aplicaciones de UWP tienen como destino CoreCLR y sus versiones de lanzamiento se compilan con la cadena de herramientas de .NET Native.By default, all UWP applications target the CoreCLR and their release builds are compiled by using the .NET Native tool chain.

  2. Tenga en cuenta que existen algunos problemas de compatibilidad conocidos entre la compilación de proyectos de aplicaciones de UWP con la cadena de herramientas de .NET Native y sin ella.Note that there are some known compatibility issues between compiling UWP app projects with the .NET Native tool chain and without it. Consulte la guía de migración para más información.Refer to the migration guide for more information.

Ahora puede escribir C# o Visual Basic código en el área expuesta .net Native que se ejecuta en el sistema local (o en el simulador).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).

Importante

A medida que vaya desarrollando la aplicación, anote cualquier uso de serialización o reflexión en el código.As you develop your app, note any use of serialization or reflection in your code.

De forma predeterminada, las compilaciones de depuración se compilan JIT para habilitar la implementación rápida de F5, mientras que las compilaciones de versión se compilan mediante la tecnología de precompilación .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. Esto significa que debe compilar y probar las compilaciones de depuración de la aplicación para asegurarse de que funcionan normalmente antes de compilarlas con la cadena de herramientas de .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.

Paso 2: Administrar el uso de reflexión y serialización adicionalesStep 2: Handle additional reflection and serialization usage

Se agrega de forma automática un archivo de directivas en tiempo de ejecución, Default.rd.xml, al proyecto cuando lo crea.A runtime directives file, Default.rd.xml, is automatically added to your project when you create it. Si desarrolla en C#, se encuentra en la carpeta Propiedades de su proyecto.If you develop in C#, it is found in your project's Properties folder. Si desarrolla en Visual Basic, se encuentra en la carpeta Mi proyecto de su proyecto.If you develop in Visual Basic, it is found in your project's My Project folder.

Nota

Para obtener información general acerca del proceso de compilación de .NET Native que proporciona información general sobre por qué se necesita un archivo de directivas en tiempo de ejecución, consulte .NET Native y compilación.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.

El archivo de directivas en tiempo de ejecución se usa para definir los metadatos que necesita la aplicación en tiempo de ejecución.The runtime directives file is used to define the metadata that your app needs at run time. En algunos casos, la versión predeterminada del archivo puede ser adecuada.In some cases, the default version of the file may be adequate. Sin embargo, es posible que algunos códigos que se basan en la serialización o la reflexión requieran entradas adicionales en el archivo de directivas en tiempo de ejecución.However, some code that relies on serialization or reflection may require additional entries in the runtime directives file.

SerializaciónSerialization

Existen dos categorías de serializadores y ambas pueden requerir entradas extra en el archivo de directivas en tiempo de ejecución:There are two categories of serializers, and both may require additional entries in the runtime directives file:

  • Serializadores no basados en la reflexión.Non-reflection based serializers. Los serializadores de la biblioteca de clases .NET Framework, como las clases DataContractSerializer, DataContractJsonSerializery XmlSerializer , no usan reflexión.The serializers found in the .NET Framework class library, such as the DataContractSerializer, DataContractJsonSerializer, and XmlSerializer classes, do not rely on reflection. Sin embargo, requieren que el código se genere en función del objeto que se va a serializar o deserializar.However, they do require that code be generated based on the object to be serialized or deserialized. Para más información, consulte la sección "Serializadores de Microsoft" en Serialization and Metadata.For more information, see the "Microsoft Serializers" section in Serialization and Metadata.

  • Serializadores de terceros.Third-party serializers. Las bibliotecas de serialización de terceros, la más común de las cuales es el serializador JSON Newtonsoft, suelen basarse en la reflexión y requieren entradas en el archivo *. Rd. XML para admitir la serialización y deserialización de objetos.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. Para más información, vea la sección "Serializadores de terceros" en Serialization and Metadata.For more information, see the "Third-Party Serializers" section in Serialization and Metadata.

Métodos basados en la reflexiónMethods that rely on reflection

En algunos casos, el uso de reflexión en el código no es obvio.In some cases, the use of reflection in code is not obvious. Algunas API comunes o patrones de programación no se consideran parte de la API de reflexión, pero se basan en la reflexión para ejecutarse correctamente.Some common APIs or programming patterns aren't considered part of the reflection API but rely on reflection to execute successfully. Esto incluye los siguientes métodos de creación de instancias de tipo y de construcción de métodos:This includes the following type instantiation and method construction methods:

Para obtener más información, consulta APIs That Rely on Reflection.For more information, see APIs That Rely on Reflection.

Nota

Los nombres de tipo que se usan en los archivos de directivas en tiempo de ejecución deben ser nombres completos.Type names used in runtime directives files must be fully qualified. Por ejemplo, el archivo debe mostrar "System.String" en lugar de "String".For example, the file must specify "System.String" instead of "String".

Paso 3: implementar y probar las compilaciones de lanzamiento de la aplicaciónStep 3: Deploy and test the release builds of your app

Después de actualizar el archivo de directivas en tiempo de ejecución, puede recompilar e implementar compilaciones de depuración de la aplicación.After you’ve updated the runtime directives file, you can rebuild and deploy release builds of your app. Los archivos binarios de .NET Native se colocan en el subdirectorio ILC. out del directorio especificado en el cuadro de texto ruta de acceso de los resultados de compilación del cuadro de diálogo propiedades del proyecto, pestaña compilar . los archivos binarios que no están en esta carpeta no se han compilado 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. Pruebe la aplicación exhaustivamente y pruebe todos los escenarios, incluidos los escenarios de error, en cada una de las plataformas de destino.Test your app thoroughly, and test all scenarios, including failure scenarios, on each of its target platforms.

Si la aplicación no funciona correctamente (en especial, en los casos donde se generen excepciones MissingMetadataException o MissingInteropDataException en tiempo de ejecución), siga las instrucciones de la siguiente sección, Paso 4: Resolver manualmente los metadatos que faltan.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. Habilitar las primeras excepciones puede ayudarle a encontrar estos errores.Enabling first-chance exceptions may help you find these bugs.

Cuando haya probado y depurado las compilaciones de depuración de la aplicación y esté seguro de que ha eliminado las excepciones MissingMetadataException y MissingInteropDataException , debe probar la aplicación como una aplicación optimizada de .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 app. Para ello, cambie la configuración del proyecto activo de Depurar a Liberar.To do this, change your active project configuration from Debug to Release.

Paso 4: Resolver manualmente los metadatos que faltanStep 4: Manually resolve missing metadata

El error más común que encontrará con .NET Native que no encuentre en el escritorio es una excepción de tiempo de ejecución MissingMetadataException, MissingInteropDataExceptiono 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. En algunos casos, la ausencia de metadatos se puede manifestar en un comportamiento impredecible o, incluso, en errores de la aplicación.In some cases, the absence of metadata can manifest itself in unpredictable behavior or even in app failures. En esta sección se describe cómo puede depurar y resolver estas excepciones agregando directivas al archivo de directivas en tiempo de ejecución.This section discusses how you can debug and resolve these exceptions by adding directives to the runtime directives file. Para obtener información sobre el formato de las directivas de tiempo de ejecución, vea Referencia del archivo de configuración de directivas en tiempo de ejecución (rd.xml).For information about the format of runtime directives, see Runtime Directives (rd.xml) Configuration File Reference. Tras agregar las directivas en tiempo de ejecución, debe implementar y volver a probar la aplicación y resolver cualquier excepción MissingMetadataException, MissingInteropDataException y MissingRuntimeArtifactException hasta que no se generen más excepciones.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.

Sugerencia

Especifique las directivas en tiempo de ejecución en un nivel elevado para que la aplicación sea resistente a los cambios de código.Specify the runtime directives at a high level to enable your app to be resilient to code changes. Recomendamos agregar directivas en tiempo de ejecución en los niveles de espacio de nombres y de tipo, en lugar de hacerlo en el nivel de miembro.We recommend adding runtime directives at the namespace and type levels rather than the member level. Tenga en cuenta que puede haber una compensación entre la resistencia y los archivos con tiempos de compilación más prolongados.Note that there may be a tradeoff between resiliency and larger binaries with longer compile times.

Considere las siguientes cuestiones si se trata de una excepción de metadatos que faltan:When addressing a missing metadata exception, consider these issues:

  • ¿Qué intentaba hacer la aplicación antes de la excepción?What was the app trying to do before the exception?

    • Por ejemplo, ¿enlazaba datos, serializaba o deserializaba datos o usaba directamente la API de reflexión?For example, was it data binding, serializing or deserializing data, or directly using the reflection API?
  • ¿Se trata de un caso aislado o cree que surgirá el mismo problema con otros tipos?Is this an isolated case, or do you believe you'll encounter the same issue for other types?

    • Por ejemplo, se genera una excepción MissingMetadataException al serializar un tipo en el modelo de objetos de la aplicación.For example, a MissingMetadataException exception is thrown when serializing a type in the app’s object model. Si sabe de otros tipos que se van a serializar, puede agregar también directivas en tiempo de ejecución para esos tipos (o para sus espacios de nombres contenedores, dependiendo de cómo esté organizado el código).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.
  • ¿Puede volver a escribir el código para que no haga uso de la reflexión?Can you rewrite the code so it doesn’t use reflection?

    • Por ejemplo, ¿utiliza el código la palabra clave dynamic cuando se sabe qué tipo esperar?For example, does the code use the dynamic keyword when you know what type to expect?

    • ¿Llama el código a un método que depende de la reflexión cuando existe una alternativa mejor?Does the code call a method that depends on reflection when some better alternative is available?

Nota

Para obtener más información sobre cómo controlar los problemas derivados de las diferencias en la reflexión y la disponibilidad de los metadatos en aplicaciones de escritorio y .NET Native, consulte API que dependen de la reflexión.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.

Si desea ver algunos ejemplos específicos de control de excepciones y otros problemas que se producen al probar la aplicación, consulte:For some specific examples of handling exceptions and other issues that occur when testing your app, see:

Vea tambiénSee also