移植到通用 Windows 平台 (C++)Porting to the Universal Windows Platform (C++)

在本主题中,可以找到有关如何将现有的 C++ 代码移植到 Windows 10 应用平台(通用 Windows 平台)的信息。In this topic, you can find information on how to port existing C++ code to the Windows 10 app platform, the Universal Windows Platform. 术语 “通用” 的意思是代码可以在运行 Windows 10 的任何设备上运行,包括桌面、手机、平板电脑和运行 Windows 10 的未来设备。What is meant by the term universal is that your code can run on any of the devices that run Windows 10, including desktop, phone, tablets, and future devices that run Windows 10. 可以创建单个项目和单个基于 XAML 的用户界面,可在运行 Windows 10 的任何设备上正常工作。You create a single project and a single XAML-base user interface that works well on any device that runs Windows 10. 可以在 XAML 中使用动态布局功能,以允许应用的 UI 适应不同的显示大小。You can use dynamic layout features in XAML to allow the app's UI to adapt to different display sizes.

Windows 开发人员中心文档包含将 Windows 8.1 应用移植到通用 Windows 平台的指南。The Windows Dev Center documentation contains a guide for porting Windows 8.1 apps to the Universal Windows Platform. 请参阅 从 Windows Runtime 8 移动到 UWPSee Move from Windows Runtime 8 to UWP. 尽管该指南主要侧重于 C# 代码,但指南的大部分内容都适用于 C++。Although the guide focused mostly on C# code, most of the guidance is applicable to C++. 下面的过程包含更加详细的信息。The following procedures contain more detailed information.

本主题包含以下用于将代码移植到 UWP 的过程。This topic contains the following procedures for porting code to the UWP.

  1. 将 Windows 8.1 应用商店应用移植到 UWPPorting a Windows 8.1 Store App to the UWP

  2. 将 Windows 8.1 运行时组件移植到 UWPPorting a Windows 8.1 Runtime Component to the UWP

    如果具有经典的桌面 Win32 DLL,并且想要从 UWP 应用程序调用它,也可以执行此操作。If you have a classic desktop Win32 DLL and you want to call it from a UWP application, you can do that as well. 使用此类过程,可以为现有经典 Windows 桌面 C++ 应用程序或跨平台标准 C++ 代码创建 UWP 用户界面层。Using such procedures, you can create a UWP user interface layer for an existing classic Windows desktop C++ application, or your cross-platform standard C++ code. 请参阅如何在通用 Windows 平台应用中使用现有 C++ 代码See How to: Use Existing C++ Code in a Universal Windows Platform App.

将 Windows 8.1 应用商店应用移植到 UWPPorting a Windows 8.1 Store App to the UWP

如果拥有 Windows 8.1 应用商店应用,则可以使用此过程使其在 UWP 和运行 Windows 10 的任何设备上正常工作。If you have a Windows 8.1 Store App, you can use this procedure to get it working on the UWP and any device that runs Windows 10. 最好首先使用 Visual Studio 2017 将项目生成为 Windows 8.1 项目,以首先消除由编译器和库中的更改所引发的任何问题。It's a good idea to first build the project with Visual Studio 2017 as a Windows 8.1 project, to first eliminate any issues that arise from changes in the compiler and libraries. 完成后,有两种方法可以将其转换为 Windows 10 UWP 项目。Once you've done that, there are two ways to convert this to a Windows 10 UWP project. 最简单的方法(如下面的过程所述)是创建通用 Windows 项目,并将现有的代码复制到其中。The easiest way (as explained in the following procedure) is to create a Universal Windows project, and copy your existing code into it. 如果对 Windows 8.1 桌面和 Windows 8.1 手机使用通用项目,则你的项目开始时在 XAML 中有两个不同的布局,但最终只有一个调整至显示大小的动态布局。If you were using a Universal project for Windows 8.1 desktop and Windows 8.1 Phone, your project will start with two different layouts in XAML but end with a single dynamic layout that adjusts to the display size.

若要将 Windows 8.1 应用商店应用移植到 UWPTo port a Windows 8.1 Store App to the UWP

  1. 如果尚未完成此操作,则在 Visual Studio 2017 中打开 Windows 8.1 应用项目,并按照说明来升级项目文件。If you have not already done so, open your Windows 8.1 App project in Visual Studio 2017, and follow the instructions to upgrade the project file.

    需要在 Visual Studio 安装程序中安装 Windows 8.1 工具。You need to have installed the Windows 8.1 Tools in Visual Studio setup. 如果没有安装这些工具,请从“程序和功能”窗口启动 Visual Studio 安装程序,选择 Visual Studio 2017,并在安装程序窗口中选择“修改”。If you don't have those tools installed, start Visual Studio setup from the Programs and Features window, choose Visual Studio 2017, and in the setup window, choose Modify. 找到 Windows 8.1 工具,确保其已选中,然后选择“确定”。Locate Windows 8.1 Tools, make sure it is selected, and choose OK.

  2. 打开“项目属性”窗口,并在“C++”、“常规”下将平台工具集设置为 v141(适用于 Visual Studio 2017 的生成工具)。Open the Project Properties window, and under C++, General, set the Platform Toolset to v141, the build tools for Visual Studio 2017.

  3. 将该项目生成为 Windows 8.1 项目,并解决任何生成错误。Build the project as a Windows 8.1 project, and address any build errors. 在此阶段的任何错误可能是由于生成工具和库中的重大更改所引起的。Any errors at this stage are probably due to breaking changes in the build tools and libraries. 有关可能会影响代码的更改的详细说明,请参阅 Visual C++ 更改历史记录(2003 - 2015)See Visual C++ change history 2003 - 2015 for a detailed explanation of the changes that might affect your code.

    一旦项目已完全生成,则可以准备移植到通用 Windows (Windows 10) 中。Once your project builds cleanly, you are ready to port to Universal Windows (Windows 10).

  4. 使用空白模板创建一个新的通用 Windows 应用项目。Create a new Universal Windows App project using the Blank template. 你可能想要将其命名为与你现有的项目相同的名称,但是若要执行此操作,项目必须存在于不同的目录中。You might want to give it the same name as your existing project, although to do that the projects must be in different directories.

  5. 关闭解决方案,然后使用 Windows 资源管理器或命令行,将 Windows 8.1 项目中的代码文件(具有扩展名 .cpp、.h 和 .xaml)复制到在步骤 1 中为该项目创建的项目文件 (.vcxproj) 所在的文件夹中。Close the solution, and then using Windows Explorer or the command line, copy the code files (with extensions .cpp, .h, and .xaml) from your Windows 8.1 project into the same folder as the project file (.vcxproj) for the project you created in step 1. 请不要复制 Package.appxmanifest 文件,并且如果拥有 Windows 8.1 桌面和手机的单独代码,则选择其中一个代码首先进行移植(之后需要执行一些工作以适应另一个代码)。Do not copy the Package.appxmanifest file, and if you have separate code for Windows 8.1 desktop and phone, choose one of them to port first (you'll have to do some work later to adapt to the other). 请确保复制子文件夹及其内容。Be sure to copy and subfolders and their contents. 如出现系统提示,请选择替换具有相同名称的所有文件。If prompted, choose to replace any files with duplicate names.

  6. 重新打开该解决方案,并从项目节点的快捷菜单中选择 “添加”、“现有项”Reopen the solution, and choose Add, Existing Item from the shortcut menu for the project node. 选择所有复制的文件,任何已存在于项目中的文件除外。Select all the files you copied, except any that are already part of the project.

    检查所有子文件夹,并确保也在其中添加这些文件。Check any subfolders and make sure to add the files in them as well.

  7. 如果使用与旧项目不同的项目名称,则打开 Package.appxmanifest 文件并更新入口点,以反映应用类的命名空间名称。If you are not using the same project name as your old project, open the Package.appxmanifest file and update the Entry Point to reflect the namespace name for the App class.

    Package.appxmanifest 文件中的 “入口点” 字段包含应用类的范围名称,其中包括包含应用类的命名空间。The Entry Point field in the Package.appxmanifest file contains a scoped name for the App class, which includes the namespace that contains the App class. 当创建通用 Windows 项目时,命名空间设置为该项目的名称。When you create a Universal Windows project, the namespace is set to the name of the project. 如果这不同于从旧项目中复制的文件的内容,则必须更新一个或另一个以使它们能够匹配。If this is different from what's in the files you copied in from your old project, you must update one or the other to make them match.

  8. 生成项目并解决由不同版本的 Windows SDK 之间的重大更改所引发的任何生成错误。Build the project, and address any build errors due to breaking changes between the different versions of the Windows SDK.

  9. 在本地桌面上运行该项目。Run the project on the Local Desktop. 验证不存在部署错误,并且应用的布局看起来合理,能在桌面上正常工作。Verify that there are no deployment errors, and that the layout of the app looks reasonable and that it functions correctly on the desktop.

  10. 如果有单独的代码文件和 .xaml 用于其他设备(如 Windows Phone 8.1),则检查此代码并确定其与标准设备的差异。If you had separate code files and .xaml for another device, such as Windows Phone 8.1, examine this code and identify where it differs from the standard device. 如果其差异仅存在于布局中,则可能能够在 xaml 中使用“视觉状态管理器”根据屏幕大小自定义显示。If the difference is only in the layout, you might be able to use a Visual State Manager in the xaml to customize the display depending on the size of the screen. 对于其他区别,可使用运用以下 #if 语句的代码中的条件部分。For other differences, you can use conditions sections in your code using the following #if statements.

    #if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_PC_APP)  
    #if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_PHONE_APP)  
    #if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)  
    #if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP)  
    

    这些语句分别适用于 Windows 应用商店应用、Windows Phone 应用商店应用、都适用或都不适用(仅针对经典 Win32 桌面)。These statements respectively apply to Windows Store apps, Windows Phone Store apps, both, or neither (classic Win32 desktop only). 这些宏仅在 Windows SDK 8.1 及更高版本中才可用,因此如果你的代码需要使用早期版本的 Windows SDK 或除 Windows 以外的其他平台进行编译,则还应考虑未定义它们中任何一个这种情况。These macros are only available in Windows SDK 8.1 and later, so if your code needs to compile with earlier versions of the Windows SDK or for other platforms besides Windows, then you should also consider the case that none of them are defined.

  11. 对应用支持的每种类型的设备,在仿真器或物理设备运行和调试应用。Run and debug the app on an emulator or physical device, for each type of device that your app supports. 若要运行仿真程序,则需在物理计算机上(而不是虚拟机上)运行 Visual Studio。To run an emulator, you need to run Visual Studio on a physical computer, not a virtual machine.

将 Windows 8.1 运行时组件移植到 UWPPorting a Windows 8.1 Runtime Component to the UWP

如果有一个 DLL 或一个已使用 Windows 8.1 应用商店应用的 Windows 运行时组件,则可以使用此过程来获取使用 UWP 和 Windows 10 的组件或 DLL。If you have a DLL or a Windows Runtime Component that already works with Windows 8.1 Store apps, you can use this procedure to get the component or DLL working with the UWP and Windows 10. 基本过程是创建新项目,然后将代码复制到其中。The basic procedure is to create a new project and copy your code into it.

将 Windows 8.1 运行时组件移植到 UWPTo port a Windows 8.1 Runtime Component to the UWP

  1. 在 Visual Studio 2017 的“新建项目”对话框中,找到“Windows 通用”节点。In the New Project dialog in Visual Studio 2017, locate the Windows Universal node. 如果看不到此节点,则首先安装 用于 Windows 10 的工具If you don't see this node, install the Tools for Windows 10 first. 选择“Windows 运行时组件” 模板,给定组件名称,然后选择“确定”按钮 。Choose the Windows Runtime Component template, give a name for your component, and choose the OK button. 组件名称将被用作命名空间名称,因此你可能想要使用与旧项目的命名空间相同的名称。The component name will be used as the namespace name, so you might want to use the same name as your old projects' namespace. 这要求你在与旧文件夹不同的文件夹中创建该项目。This requires that you create the project in a different folder from the old one. 如果选择了一个不同的名称,则可以在生成的代码文件中更新命名空间名称。If you choose a different name, you can update the namespace name in the generated code files.

  2. 关闭该项目。Close the project.

  3. 将所有代码文件(.cpp、.h、.xaml 等)从 Windows 8.1 组件复制到新创建的项目中。Copy all the code files (.cpp, .h, .xaml, etc.) from your Windows 8.1 component into your newly created project. 不要复制 Package.appxmanifest 文件。Do not copy the Package.appxmanifest file.

  4. 生成,然后解决由不同版本的 Windows SDK 之间的重大更改所引发的任何错误。Build, and resolve any errors due to breaking changes between different versions of the Windows SDK.

疑难解答Troubleshooting

在将代码移植到通用 Windows 平台的过程中,可能会遇到各种错误。You might encounter various errors during the process of porting code to the Universal Windows Platform. 以下是一些可能遇到的问题。Here are some of the possible problems you might encounter.

项目配置问题Project Configuration Issues

可能会收到以下错误:You might receive the error:

could not find assembly 'platform.winmd': please specify the assembly search path using /AI or by setting the LIBPATH environment variable  

如果发生这种情况,该项目不会生成为 Windows 通用项目。If this happens, the project is not building as a Windows Universal project. 检查项目文件,并确保其具有可将项目标识为 Windows 通用项目的正确的 XML 元素。Check the project file and make sure it has the correct XML elements that identify a project as a Windows Universal Project. 此时应该会存在以下元素(目标平台的版本号可能不同):The following elements should be present (the version number of the target platform might be different):

<AppContainerApplication>true</AppContainerApplication>  
<ApplicationType>Windows Store</ApplicationType>  
<WindowsTargetPlatformVersion>10.0.10156.0</WindowsTargetPlatformVersion>  
<WindowsTargetPlatformMinVersion>10.0.10156.0</WindowsTargetPlatformMinVersion>  
<ApplicationTypeRevision>10.0</ApplicationTypeRevision>  

如果使用 Visual Studio 创建新的通用 Windows 平台项目,则不应看到此错误。If you created a new Universal Windows Platform project using Visual Studio, you should not see this error.

另请参阅See Also

Visual C++ 移植指南 Visual C++ Porting Guide
开发通用 Windows 平台 (UWP) 的应用Develop apps for the Universal Windows Platform (UWP)