.NET Native 使用者入門Getting Started with .NET Native

不論是為了 Windows 10 撰寫新的 Windows 應用程式,或是移轉現有的 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. 若要建立 .NET Native 應用程式,請遵循下列步驟:To create a .NET Native app, follow these steps:

  1. 開發以 Windows 10 為目標的通用 Windows 平台 (UWP) 應用程式,並測試應用程式的偵錯組建,以確保運作正常。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. 處理其他反映和序列化使用方式Handle additional reflection and serialization usage.

  3. 部署並測試應用程式的發行組建Deploy and test the release builds of your app.

  4. 手動解決遺漏中繼資料的問題,然後重複 步驟 3 直到所有問題解決為止。Manually resolve missing metadata, and repeat step 3 until all issues are resolved.

注意

如果您要將現有的 Windows Store 應用程式遷移至 .NET Native,請務必檢查將 您的 Windows Store 應用程式遷移至 .NET NativeIf you are migrating an existing Windows Store app to .NET Native, be sure to review Migrating Your Windows Store App to .NET Native.

步驟 1:開發並測試 UWP 應用程式的偵錯組建Step 1: Develop and test debug builds of your UWP app

不論您要開發新的應用程式,或移轉現有的應用程式,都會遵循與所有 Windows 應用程式相同的程序。Whether you are developing a new app or migrating an existing one, you follow the same process as for any Windows app.

  1. 使用適用於 Visual C# 或 Visual Basic 的通用 Windows 應用程式範本,在 Visual Studio 中建立新的 UWP 專案。Create a new UWP project in Visual Studio by using the Universal Windows app template for Visual C# or Visual Basic. 根據預設,所有 UWP 應用程式都會以 CoreCLR 為目標,而其發行組建則使用 .NET Native 工具鏈進行編譯。By default, all UWP applications target the CoreCLR and their release builds are compiled by using the .NET Native tool chain.

  2. 請注意,使用 .NET Native 工具鏈編譯 UWP 應用程式專案與不使用此工具進行編譯之間有一些已知的相容性問題。Note that there are some known compatibility issues between compiling UWP app projects with the .NET Native tool chain and without it. 如需詳細資訊,請參閱 移轉指南Refer to the migration guide for more information.

您現在可以針對在本機系統 (或模擬器) 中執行的 .NET Native 介面區,撰寫 c # 或 Visual Basic 程式碼。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).

重要

當您開發應用程式時,請記下在程式碼中使用的任何序列化或反映。As you develop your app, note any use of serialization or reflection in your code.

根據預設,debug 組建會以 JIT 編譯來啟用快速的 F5 部署,而發行組建則是使用 .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. 這表示您應該建置並測試應用程式的偵錯組建以確保運作正常,再使用 .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.

步驟 2:處理其他的反映和序列化使用Step 2: Handle additional reflection and serialization usage

當您建立專案時會自動將執行階段指示詞檔 Default.rd.xml 加入您的專案。A runtime directives file, Default.rd.xml, is automatically added to your project when you create it. 如果您以 C# 進行開發,它位於您專案的 [屬性] **** 資料夾。If you develop in C#, it is found in your project's Properties folder. 如果您以 Visual Basic 進行開發,它位於您專案的 [我的專案] **** 資料夾。If you develop in Visual Basic, it is found in your project's My Project folder.

注意

如需 .NET 原生編譯程序的概觀 (其提供需要執行階段指示詞檔案的背景資訊),請參閱 .NET 原生和編譯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.

執行階段指示詞檔案會用來定義您的應用程式在執行階段所需的中繼資料。The runtime directives file is used to define the metadata that your app needs at run time. 在某些情況下,檔案的預設版本應已足夠。In some cases, the default version of the file may be adequate. 不過,某些相依於序列化或反映的程式碼可能需要執行階段指示詞檔案中的其他項目。However, some code that relies on serialization or reflection may require additional entries in the runtime directives file.

序列化Serialization

序列化程式可分為兩種類別,這兩種類別都需要執行階段指示詞檔案中的其他項目:There are two categories of serializers, and both may require additional entries in the runtime directives file:

  • 非反映型序列化程式。Non-reflection based serializers. .NET Framework 類別庫中不依賴反映的序列化程式,例如 DataContractSerializerDataContractJsonSerializerXmlSerializer 類別。The serializers found in the .NET Framework class library, such as the DataContractSerializer, DataContractJsonSerializer, and XmlSerializer classes, do not rely on reflection. 不過,這些序列化程式需要依據所要序列化或還原序列化的物件來產生程式碼。However, they do require that code be generated based on the object to be serialized or deserialized. 如需詳細資訊,請參閱 Serialization and Metadata中的<Microsoft 序列化程式>一節。For more information, see the "Microsoft Serializers" section in Serialization and Metadata.

  • 協力廠商序列化程式。Third-party serializers. 協力廠商序列化程式庫是最常見的 Newtonsoft JSON 序列化程式,通常是以反映為基礎,而且需要.rd.xml 檔中的專案, * 以支持對象序列化和還原序列化。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. 如需詳細資訊,請參閱 Serialization and Metadata中的<協力廠商序列化程式>一節。For more information, see the "Third-Party Serializers" section in Serialization and Metadata.

依賴反映的方法Methods that rely on reflection

在某些情況下,很難察覺程式碼中是否有使用反映。In some cases, the use of reflection in code is not obvious. 某些常見的 API 或程式設計模式不是反映 API 的一部分,但依賴反映才能順利執行。Some common APIs or programming patterns aren't considered part of the reflection API but rely on reflection to execute successfully. 其中包括下列類型具現化和方法建構方法:This includes the following type instantiation and method construction methods:

如需詳細資訊,請參閱 APIs That Rely on ReflectionFor more information, see APIs That Rely on Reflection.

注意

執行階段指示詞檔案中使用的類型名稱必須是完整名稱。Type names used in runtime directives files must be fully qualified. 例如,檔案必須指定 "System.String",而不是 "String"。For example, the file must specify "System.String" instead of "String".

步驟 3:部署並測試應用程式的發行組建Step 3: Deploy and test the release builds of your app

更新執行階段指示詞檔案之後,您可以重建並部署應用程式的發行組建。After you’ve updated the runtime directives file, you can rebuild and deploy release builds of your app. .NET Native 二進位檔會放在專案的 [屬性] 對話方塊的 [組建輸出路徑] 文字方塊中指定之目錄的 [ilc.out] 子目錄中,[編譯] 索引標籤。未在此資料夾中的二進位檔未使用 .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. 請在其目標平台上完整測試您的應用程式,並測試所有情況,包括失敗情況。Test your app thoroughly, and test all scenarios, including failure scenarios, on each of its target platforms.

如果您的應用程式無法正常運作 (特別是如果在執行階段擲回 MissingMetadataExceptionMissingInteropDataException 例外狀況),請遵循下一節步驟 4:手動解決遺漏中繼資料的問題中的指示進行。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. 啟用第一個可能發生的例外狀況可協助您尋找這些錯誤。Enabling first-chance exceptions may help you find these bugs.

當您已測試並調試您的應用程式的偵錯工具組建,並確信您消除了 MissingMetadataExceptionMissingInteropDataException 例外狀況之後,您應該將應用程式測試為優化的 .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. 若要執行這項操作,請將使用中的專案組態從 [偵錯] **** 變更為 [發行] ****。To do this, change your active project configuration from Debug to Release.

步驟 4:手動解決遺漏中繼資料的問題Step 4: Manually resolve missing metadata

您在桌面上不會遇到的 .NET Native 最常見的失敗,就是執行時間 MissingMetadataExceptionMissingInteropDataExceptionMissingRuntimeArtifactException 例外狀況。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. 在某些情況下,缺少中繼資料會發生未預期的行為,甚至導致應用程式失敗。In some cases, the absence of metadata can manifest itself in unpredictable behavior or even in app failures. 本節討論如何將指示詞加入至執行階段指示詞檔案,來偵錯及解決這些例外狀況。This section discusses how you can debug and resolve these exceptions by adding directives to the runtime directives file. 如需執行階段指示詞格式的資訊,請參閱執行階段指示詞 (rd.xml) 組態檔參考For information about the format of runtime directives, see Runtime Directives (rd.xml) Configuration File Reference. 新增執行階段指示詞之後,您應該重新部署和測試應用程式,並解決任何新的 MissingMetadataExceptionMissingInteropDataExceptionMissingRuntimeArtifactException 例外狀況,直到未遇到其他任何例外狀況為止。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.

提示

在較高層級指定執行階段指示詞,可讓應用程式彈性地回應程式碼變更。Specify the runtime directives at a high level to enable your app to be resilient to code changes. 建議在命名空間和類型層級加入執行階段指示詞,而不是在成員層級加入執行階段指示詞。We recommend adding runtime directives at the namespace and type levels rather than the member level. 請注意,您可能需要在彈性與較大二進位檔案需要更長編譯時間之間進行取捨。Note that there may be a tradeoff between resiliency and larger binaries with longer compile times.

解決遺漏中繼資料的例外狀況時,請考慮下列問題:When addressing a missing metadata exception, consider these issues:

  • 發生例外狀況之前,應用程式正嘗試執行哪項作業?What was the app trying to do before the exception?

    • 例如,應用程式正在執行資料繫結、序列化或還原序列化資料,還是直接使用反映 API?For example, was it data binding, serializing or deserializing data, or directly using the reflection API?
  • 這是獨立案例,還是您認為其他類型也會遇到相同問題?Is this an isolated case, or do you believe you'll encounter the same issue for other types?

    • 例如,當序列化應用程式物件模型中的類型時,擲回 MissingMetadataException 例外狀況。For example, a MissingMetadataException exception is thrown when serializing a type in the app’s object model. 如果您知道即將序列化其他類型,您可以同時針對這些類型 (視程式碼組織程度而定也可能針對其包含命名空間) 加入執行階段指示詞。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.
  • 是否可以重寫程式碼使其不使用反映?Can you rewrite the code so it doesn’t use reflection?

    • 例如,當您知道預期類型時,程式碼是否使用 dynamic 關鍵字?For example, does the code use the dynamic keyword when you know what type to expect?

    • 程式碼是否在有一些更佳的替代方案時,呼叫相依於反映的方法?Does the code call a method that depends on reflection when some better alternative is available?

注意

如需處理源自于桌面應用程式和 .NET Native 中的反映和中繼資料可用性差異之問題的詳細資訊,請參閱 依賴反映的 apiFor 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.

如需處理測試應用程式時所發生之例外狀況和其他問題的一些特定範例,請參閱:For some specific examples of handling exceptions and other issues that occur when testing your app, see:

另請參閱See also