迁移指南:MFC ScribblePorting Guide: MFC Scribble

本主题是向你介绍 Visual C++ 项目升级过程的几个主题中的第一个主题,具体升级过程为将在较旧版本的 Visual Studio 中创建的 Visual C++ 项目升级到 Visual Studio 2017。This topic is the first of several topics that introduce you to the upgrade procedure for Visual C++ projects that were created in older versions of Visual Studio to Visual Studio 2017. 这些主题通过示例介绍升级过程,从非常简单的项目开始,过渡到稍微更复杂的项目。These topics introduce the upgrade process by example, starting with a very simple project and moving to slightly more complex ones. 在本主题中,我们将完成特定项目 (MFC Scribble) 的升级过程。In this topic, we work through the upgrade process for a specific project, MFC Scribble. 它很适合作为对 C++ 项目升级过程的基本介绍。It is suitable as a basic introduction to the upgrade process for C++ projects.

每个版本的 Visual Studio 都可能引入不兼容问题,使从较早版本的 Visual Studio 移动代码到较新的版本变得复杂。Each version of Visual Studio introduces possible incompatibilities that can complicate moving code from an older version of Visual Studio to a newer one. 有时需要对你的代码进行必要的更改,因此你必须重新编译并更新代码,有时需要对项目文件进行必要的更改。Sometimes the required changes are in your code, so you must recompile and update your code, and sometimes the required changes are to the project files. 当你打开使用早期版本的 Visual Studio 创建的项目时,Visual Studio 会自动询问你是否要将项目或解决方案更新到最新版本。When you open a project that was created with a previous version of Visual Studio, Visual Studio automatically asks you whether to update a project or solution to the latest version. 这些工具通常仅升级项目文件;它们不修改你的源代码。These tools usually upgrade only the project files; they do not modify your source code.

MFC ScribbleMFC Scribble

MFC Scribble 是一个众所周知的示例,已包括在许多不同版本的 Visual C++ 中。MFC Scribble is a well-known sample that has been included in many different releases of Visual C++. 它是一个简单的绘图应用程序,展示了 MFC 的一些基本功能。It's a simple drawing application that illustrates some of the basic features of MFC. 它有各种可用的版本,包括托管版本和本机代码版本。There are various versions of it available, including both managed and native code versions. 针对此示例,我们发现本机代码中的旧版 Scribble 来自 Visual Studio 2005 并在 Visual Studio 2017 中打开。For this example, we found an old version of Scribble in native code from Visual Studio 2005 and opened it in Visual Studio 2017.

在尝试升级之前,请确保已安装 Windows Desktop 工作负载。Before attempting to upgrade, make sure that you have the Windows Desktop workload installed. 打开 Visual Studio 安装程序 (vs_installer.exe)。Open the Visual Studio installer (vs_installer.exe). 打开安装程序的方法之一是,选择“文件”>“新建项目”,向下滚动已安装模板列表,直到看到“打开 Visual Studio 安装程序”。One way to open the installer is to choose File | New Project and scroll to the bottom of the list of installed templates until you see "Open Visual Studio Installer". 打开安装程序后,将看到所有可用的工作负载。After opening the installer you will see all the available workloads. 如果未选择“Windows Desktop 工作负载”框,请选择它,然后单击窗口底部的“修改”按钮。If the box for the Windows Desktop workload is not selected, then select it and click the Modify button at the bottom of the window.

接下来,备份整个解决方案及其所有内容。Next, back up the entire solution and all its contents.

最后,我们需要确定具体的升级方法。Finally, we needed to decide on the specific method of upgrade. 对于更复杂的解决方案和长期未进行升级的项目,则应考虑一次升级一个 Visual Studio 版本。For more complex solutions and projects that haven't been upgraded for a long time, you should consider upgrading one version of Visual Studio at a time. 这样一来,你可以对哪个 Visual Studio 版本引入了问题进行范围缩小。That way, you can narrow down which version of Visual Studio introduced a problem. 对于简单的项目,值得在最新版的 Visual Studio 中尝试打开它,并允许向导将项目转换。For a simple project, it's worth trying to open it in the latest version of Visual Studio and allowing the wizard to convert the project. 如果这不起作用,你可以尝试一次升级一个版本(如果你有权访问相应版本的 Visual Studio)。If that doesn't work, you can try upgrading one version at a time, if you have access to the appropriate versions of Visual Studio.

请注意,使用 /Upgrade 选项(而不是使用向导来升级项目),你还可以在命令行运行 devenv。Note that you can also run devenv at the command line, using the /Upgrade option, instead of using the wizard to upgrade your projects. 请参阅 /Upgrade (devenv.exe)See /Upgrade (devenv.exe). 这在为大量项目自动执行升级过程中很有帮助。That could be helpful in automating the upgrade process for a large number of projects.

步骤 1。Step 1. 转换项目文件Converting the Project File

在 Visual Studio 2017 中打开旧的项目文件时,Visual Studio 主动将项目文件转换为我们接受的最新版本。When you open an old project file in Visual Studio 2017, Visual Studio offers to convert the project file to the most recent version, which we accepted. 出现了下面的对话框:The following dialog box appeared:

复查项目和解决方案更改Review Project and Solution Changes

出现了错误,通知我们 Itanium 目标不可用且不被转换。An error occurred notifying us that the Itanium target is not available and won't be converted.

Platform 'Itanium' is missing from this project. All the configurations and their file configuration settings specific to this platform will be ignored. If you want this platform converted, please make sure you have the corresponding platform installed under '%vctargetpath%\platforms\Itanium'.Continue to convert this project without this platform?  

创建之前的 Scribble 项目时,Itanium 是重要的目标平台。At the time the previous Scribble project was created, Itanium was an important target platform. Windows 平台不再支持 Itanium,因此我们选择在不支持 Itanium 平台的情况下继续。The Windows platform no longer supports Itanium, so we chose to continue without supporting the Itanium platform.

Visual Studio 随后将显示一个迁移报告,该报告列出旧项目文件中的所有问题。Visual Studio then displayed a migration report listing all of the issues with the old project file.

升级报告Upgrade Report

在本例中,问题都是警告,并且 Visual Studio 在项目文件中进行了相应的更改。In this case, the issues were all warnings, and Visual Studio made the appropriate changes in the project file. 项目关注的最大差别就在于生成工具从 vcbuild 更改为 msbuild。The big difference as far as the project is concerned is that the build tool changed from vcbuild to msbuild. 在 Visual Studio 2010 中首先引入了此更改。This change was first introduced in Visual Studio 2010. 其他更改包括项目文件本身中元素序列的重新排列。Other changes include some rearrangement of the sequence of elements in the project file itself. 针对此简单项目,无需对这些问题进行深入关注。None of the issues required further attention for this simple project.

步骤 2。Step 2. 开始生成Getting it to build

在生成之前,我们检查平台工具集以便了解项目系统使用的是何种编译器版本。Before building, we check the platform toolset so we know what compiler version the project system is using. 在“配置属性”之下的“项目属性”对话框中,请在“常规”类别中查看“平台工具集”属性。In the project properties dialog, under Configuration Properties, in the General category, look at the Platform Toolset property. 它包含 Visual Studio 的版本和平台工具版本号,在本例中,Visual Studio 2017 版本的工具版本号为 v141。It contains the version of Visual Studio and the platform tool version number, which in this case is v141 for the Visual Studio 2017 version of the tools. 转换使用 Visual C++ 2010、2012、2013 或 2015 进行初始编译的项目时,工具集将不会自动更新为 Visual Studio 2017 工具集。When you convert a project that was originally compiled with Visual C++ 2010, 2012, 2013 or 2015, the toolset is not automatically updated to the Visual Studio 2017 toolset.

若要切换到 Unicode,请打开“配置属性”之下的项目属性,选择“常规”部分,然后找到“字符集”属性。To make the switch to Unicode, open the project's properties, under Configuration Properties, choose the General section, and locate the Character Set property. 将此项从“使用多字节字符集”更改为“使用 Unicode 字符集”。Change this from Use Multi-Byte Character Set to Use Unicode Character Set. 此更改的效果:现在定义了 _UNICODE 和 UNICODE 宏,而未定义 _MBCS,这一点你可以在“命令行”属性处的“C/C++”类别之下的“属性”对话框中进行验证。The effect of this change is that now the _UNICODE and UNICODE macros are defined and _MBCS is not, which you can verify in the properties dialog under the C/C++ category at the Command Line property.

/GS /analyze- /W4 /Zc:wchar_t /Zi /Gm- /Od /Fd".\Debug\vc141.pdb" /Zc:inline /fp:precise /D "_AFXDLL" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_UNICODE" /D "UNICODE" /errorReport:prompt /WX /Zc:forScope /Gd /Oy- /MDd /Fa".\Debug\" /EHsc /nologo /Fo".\Debug\" /Fp".\Debug\Scribble.pch" /diagnostics:classic 

尽管未将 Scribble 项目设置为使用 Unicode 字符进行编译,但它已使用 TCHAR(而非 char)进行编写,因此实际上无需做任何更改。Although Scribble project wasn't set up to compile with Unicode characters, it was already written with TCHAR instead of char, so nothing actually needs to be changed. 使用 Unicode 字符集成功生成项目。The project builds successfully with the Unicode character set.

至此解决方案构建完毕。Now build the solution. 在输出窗口中,编译器告诉我们 _WINNT32_WINNT 未进行定义:In the output window, the compiler tells us that _WINNT32_WINNT is not defined:

_WIN32_WINNT not defined. Defaulting to _WIN32_WINNT_MAXVER (see WinSDKVer.h)  

这是一个警告而不是错误,在升级 Visual C++ 项目时很常见。This is a warning, not an error, and is very common when upgrading a Visual C++ project. 这是定义我们的应用程序将在其上运行的最低版本的 Windows 的宏。This is the macro that defines what the lowest version of Windows that our application will run on. 如果我们忽略该警告,则接受表示当前 Windows 版本的默认值(_WIN32_WINNT_MAXVER)。If we ignore the warning, we accept the default value, _WIN32_WINNT_MAXVER, which means the current version of Windows. 有关可能的值的表,请参阅 Using the Windows Headers(使用 Windows 标头)。For a table of possible values, see Using the Windows Headers. 例如,我们可以将其设置为自 Vista 起的任何版本上运行。For example, we can set it to run on any version from Vista onwards.

#define _WIN32_WINNT _WIN32_WINNT_VISTA  

如果代码使用你用此宏该指定的 Windows 版本上不可用的部分 Windows API,则你应该将其视为编译器错误。If the code uses parts of the Windows API that aren't available on the version of Windows that you specify with this macro, you should see that as a compiler error. 对于 Scribble 代码,不存在任何错误。In the case of the Scribble code, there is no error.

步骤 3。Step 3. 测试和调试Testing and debugging

由于没有任何测试套件,因此我们只是启动应用,通过用户界面手动测试其功能。There is no test suite, so we just started the app, tested its features manually through the UI. 观察不到任何问题。No issues were observed.

步骤 4。Step 4. 改进代码Improve the code

现在你已经迁移到 Visual Studio 2017,建议执行一些更改来利用新的 C++ 功能。Now that you've migrated to Visual Studio 2017, you might want to make some changes to take advantage of new C++ features. 当前版本的 Visual C++ 编译器相比早期版本更符合 C++ 标准,因此如果想做一些代码更改以使代码更加安全,并更易于移植到其他编译器和操作系统上,则应考虑做些改进。The current version of Visual C++ compiler is much more conformant to the C++ standard then previous versions, so if you have a mind to make some code changes to make your code more secure, and more portable to other compilers and operating systems, you should consider some improvements.

后续步骤Next steps

Scribble 是一款小巧而简单 Windows 桌面应用程序,且不难转换。Scribble was a small and simple Windows desktop application, and it wasn't hard to convert. 许多小型简单的应用程序都可轻松转换为新版本。Many small, simple apps convert just as easily to the new version. 对于具有很多行代码以及可能不符合现代设计标准的较早的旧版代码、多个项目和库、自定义生成步骤的更复杂的应用程序,或对于复杂脚本的自动生成,则需要较长时间进行升级。For more complex applications, with many more lines of code, older legacy code that might not be up to modern engineering standards, multiple projects and libraries, custom build steps, or for complex scripted automated builds, it will take more time to upgrade. 继续下一个示例,即称为 COM Spy 的 ATL/COM 应用程序。Continue with the next example, an ATL/COM application called COM Spy.

另请参阅See Also

移植和升级:示例和案例研究 Porting and Upgrading: Examples and Case Studies
下一个示例:COM SpyNext Example: COM Spy