如何使用 Visual C++ 工具集或文档报告问题How to report a problem with the Visual C++ toolset or documentation

使用 Microsoft Visual C++ 编译器、链接器或其他工具和库时如果遇到问题,请告知我们。If you encounter problems with the Microsoft Visual C++ compiler, linker, or other tools and libraries, we want to know about them. 如果文档中存在问题,我们也想要了解。If the issue is in our documentation, we want to know about that, too.

如何报告 C++ 工具集问题How to report a C++ toolset issue

最好是向我们发送报告,在报告中说明你所遇到的问题、如何生成程序的详细信息,以及重现(我们可用于在自己的计算机上重现该问题的完整测试用例)。The best way to let us know about a problem is to send us a report that includes a description of the problem you've encountered, details about how you're building your program, and a repro, a complete test case we can use to reproduce the problem on our own machines. 通过这些信息,我们可以快速验证问题是存在于我们的代码中还是你的本地环境中,判断它是否会影响其他版本的编译器,并诊断其原因。This information lets us quickly verify that the problem exists in our code and is not local to your environment, to determine whether it affects other versions of the compiler, and to diagnose its cause.

在本部分中,可了解好的报告所包含的内容、如何生成所发现问题类型的报告,以及如何将报告发送给产品团队。In the sections below, you'll read about what makes a good report, how to generate a repro for the kind of issue you've found, and how to send your report to the product team. 无论对我们,还是对和你一样的其他开发者而言,你的报告都十分重要。Your reports are important to us and to other developers like you. 谢谢你帮助我们改进 Visual C++!Thank you for helping us improve Visual C++!

如何准备报告How to prepare your report

创建高质量报告非常重要,因为如果缺少完整信息,我们很难在自己的计算机上重现所遇到的问题。Creating a high-quality report is important because it is very difficult to reproduce the problem you encountered on our own machines without complete information. 报告的质量越高,我们重新创建和诊断问题的效率就越高。The better your report is, the more effectively we are able recreate and diagnose the problem.

报告中应至少包括At a minimum, your report should contain

  • 正在使用的工具集的完整版本信息。The full version information of the toolset you're using.

  • 用于生成代码的完整 cl.exe 命令行。The full cl.exe command line used to build your code.

  • 对所遇到问题的详细描述。A detailed description of the problem you encountered.

  • 重现:简单完整的自包含源代码示例,用于演示问题。A repro: a complete, simplified, self-contained source code example that demonstrates the problem.

继续阅读,详细了解我们需要的特定信息,在何处可以找到它们,以及如何创建高质量重现。Read on to learn more about the specific information we need and where you can find it, and how to create a good repro.

工具集版本The toolset version

我们需要引发问题的工具集的完整版本信息和目标体系结构,以便在我们的计算机上针对相同工具集测试你的重现。We need the full version information and the target architecture of the toolset that causes the problem so that we can test your repro against the same toolset on our machines. 如果我们可以重现此问题,我们还可以将此信息作为起点,调查哪些版本的工具集存在同样的问题。If we can reproduce the problem, this information also gives us a starting point to investigate which other versions of the toolset exhibit the same problem.

报告你正在使用的编译器的完整版本To report the full version of the compiler you're using

  1. 打开与用于生成项目的 Visual Studio 版本和配置体系结构匹配的“开发人员命令提示”。Open the Developer Command Prompt that matches the Visual Studio version and configuration architecture used to build your project. 例如,如果在 x64 上使用 Visual Studio 2017 生成面向 x64 的项目,请选择“适用于 VS 2017 的 x64 本机工具命令提示”。For example, if you build by using Visual Studio 2017 on x64 for x64 targets, choose x64 Native Tools Command Prompt for VS 2017. 有关详细信息,请参阅开发人员命令提示快捷方式For more information, see Developer command prompt shortcuts.

  2. 在“开发人员命令提示”控制台窗口中,输入命令 cl/Bv。In the developer command prompt console window, enter the command cl /Bv.

该输出应与以下类似:The output should look similar to this:

C:\Users\username\Source>cl /Bv
Microsoft (R) C/C++ Optimizing Compiler Version 19.14.26428.1 for x86
Copyright (C) Microsoft Corporation.  All rights reserved.

Compiler Passes:
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\cl.exe:        Version 19.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\c1.dll:        Version 19.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\c1xx.dll:      Version 19.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\c2.dll:        Version 19.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\link.exe:      Version 14.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\mspdb140.dll:  Version 14.14.26428.1
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Tools\MSVC\14.14.26428\bin\HostX86\x86\1033\clui.dll: Version 19.14.26428.1

cl : Command line error D8003 : missing source filename

将整个输出复制并粘贴到报告。Copy and paste the entire output into your report.

命令行The command line

我们需要用于生成代码的确切命令行(cl.exe 及其全部参数),以便以完全相同的方式在自己的计算机上生成它。We need the exact command line (cl.exe and all of its arguments) used to build your code, so that we can build it in exactly the same way on our machines. 这一点很重要,因为你所遇到的问题可能仅在使用某一特定参数或参数组合生成时才存在。This is important because the problem you've encountered might only exist when building with a certain argument or combination of arguments.

此信息位于遇到问题后立即出现的生成日志中,建议在该位置查找。The best place to find this information is in the build log immediately after experiencing the problem. 这可确保命令行包含完全相同的参数,从而有可能帮助解决问题。This ensures that the command line contains exactly the same arguments that might be contributing to the problem.

报告命令行的内容To report the contents of the command line

  1. 找到并打开 CL.command.1.tlog 文件。Locate the CL.command.1.tlog file and open it. 默认情况下,此文件位于“文档”文件夹下的 \Visual Studio version\Projects\SolutionName\ProjectName\Configuration\ProjectName.tlog\CL.command.1.tlog 或“用户”文件夹下的 \Source\Repos\SolutionName\ProjectName\Configuration\ProjectName.tlog\CL.command.1.tlog 中。By default, this file is located in your Documents folder in \Visual Studio version\Projects\SolutionName\ProjectName\Configuration\ProjectName.tlog\CL.command.1.tlog, or in your User folder under \Source\Repos\SolutionName\ProjectName\Configuration\ProjectName.tlog\CL.command.1.tlog. 如果使用其他生成系统,或更改了项目的默认位置,则该文件可能位于其他位置。It may be in a different location if you use another build system or if you have changed the default location for your project.

    可在此文件中找到源代码文件的名称,其后是用于编译它们的命令行参数(每个分占一行)。Inside this file, you'll find the names of source code files followed by the command line arguments used to compile them, each on separate lines.

  2. 找到包含源代码文件名称的行(问题发生之处);其下方的行包含相应的 cl.exe 命令参数。Locate the line that contains the name of the source code file where the problem occurs; the line below it contains the corresponding cl.exe command arguments.

将整个命令行复制并粘贴到报告。Copy and paste the entire command line into your report.

问题说明A description of the problem

我们需要一份有关你所遇到问题的详细说明,以验证是否可以在我们的计算机上观察到相同的效果;有时,它还有助于使我们了解你所尝试完成的内容,以及你希望看到的结果。We need a detailed description of the problem you've encountered so that we can verify that we see the same effect on our machines; its also sometimes useful for us to know what you were trying to accomplish, and what you expected to happen.

请提供工具集给出的确切错误消息,或者看到的确切运行时行为。Please provide the exact error messages given by the toolset, or the exact runtime behavior you see. 我们需要此信息来验证是否已正确重现问题。We need this information to verify that we've properly reproduced the issue. 请提供所有编译器输出,而不仅仅是最后一个错误消息。Please include all of the compiler output, not just the last error message. 我们需要查看与所报告问题相关的所有信息。We need to see everything that led up to the issue you report. 如果可以使用命令行编译器来复制问题,则首选编译器输出;IDE 和其他生成系统可能会筛选你看到的错误消息,或者仅捕获错误消息的第一行。If you can duplicate the issue by using the command line compiler, that compiler output is preferred; the IDE and other build systems may filter the error messages you see, or only capture the first line of an error message.

如果问题是编译器接受无效的代码并且未生成诊断,请在报告中注明。If the issue is that the compiler accepts invalid code and does not generate a diagnostic, please note this in your report.

若要报告运行时行为问题,请提供该程序输出内容的原样副本,和你想要看到的内容。To report a runtime behavior problem, include an exact copy of what the program prints out, and what you expect to see. 理想情况下,它嵌入在输出语句本身中,例如,printf("This should be 5: %d\n", actual_result);Ideally, this is embedded in the output statement itself, for example, printf("This should be 5: %d\n", actual_result);. 如果程序崩溃或挂起,也请提到这一点。If your program crashes or hangs, mention that as well.

添加任何其他可能有助于我们诊断你遇到的问题的详细信息,例如,你可能已发现的任何变通方法。Add any other details that might help us diagnose the problem you experienced, such as any work-arounds you may have found. 避免在报表的其他部分出现重复信息。Avoid repeating information found elsewhere in your report.

重现The repro

重现是完整的自包含源代码示例,可重复演示你遇到的问题(这就是重现这个名字的由来)。A repro is a complete, self-contained source code example that reproducibly demonstrates the problem you've encountered (hence the name). 我们需要重现来在自己的计算机上重现错误。We need a repro so that we can reproduce the error on our machines. 代码本身应该足以创建可编译和运行的简单可执行文件,或者在没有出现发现的问题时可以编译和运行的简单可执行文件。The code should be sufficient by itself to create a simple executable that compiles and runs, or that would compile and run if not for the problem you've found. 重现不是代码片段;它应具有完整的函数和类,并包含所有必要 #include 指令,即使对于标准标头也是如此。A repro is not a code snippet; it should have complete functions and classes and contain all the necessary #include directives, even for the standard headers.

高质量重现的标准What makes a good repro

高质量重现的标准为:A good repro is:

  • 最小的。Minimal. 重现应尽可能最小,但仍能准确演示所遇到的问题。Repros should be as small as possible yet still demonstrate exactly the problem you encountered. 重现无需复杂或真实;它们只需要显示符合标准或记录的编译器实现的代码,或者在缺少诊断的情况下显示不合规的代码。Repros do not need to be complex or realistic; they only need to show code that conforms to the Standard or the documented compiler implementation, or in the case of a missing diagnostic, the code that is not conformant. 重现应简明扼要,最好只包含刚好足够演示问题的代码。Simple, to-the-point repros that contain just enough code to demonstrate the problem are best. 如果删除或简化某些代码也能保持符合性,并且不改变问题,请进行删除或简化。If you can eliminate or simplify the code and remain conformant and also leave the issue unchanged, please do so. 不需要提供有效代码的反例。You do not need to include counter-examples of code that works.

  • 自包含。Self-Contained. 重现应避免不需要的依赖项。Repros should avoid unnecessary dependencies. 如果无需第三方库就可重现,请直接重现。If you can reproduce the problem without third-party libraries, please do so. 如果无需任何库代码,只需简单的输出语句(例如,puts("this shouldn't compile");std::cout << value;printf("%d\n", value);)即可重现此问题,请使用简单的输出语句。If you can reproduce the problem without any library code besides simple output statements (for example, puts("this shouldn't compile");, std::cout << value;, and printf("%d\n", value); are okay), please do so. 最理想的情况是,示例可以压缩为单个源代码文件,而不引用任何用户标头。It's ideal if the example can be condensed to a single source code file, without reference to any user headers. 尽可能减少我们需要考虑的有利于解决问题的代码量,这对我们而言极为有用。Reducing the amount of code we have to consider as a possible contributor to the problem is enormously helpful to us.

  • 针对最新版本的编译器。Against the latest compiler version. 重现应尽可能使用最新版本的工具集的最新更新,或者下一次更新或下一个主版本的最新预发布版本。Repros should use the most recent update to the latest version of the toolset, or the most recent prerelease version of the next update or next major release, whenever possible. 在旧版本工具集中可能会遇到的问题很可能已在新版本中得到修复。Problems you may encounter in older versions of the toolset have very often been fixed in newer versions. 只有在特殊情况下,才会将修复向后移植到旧版本。Fixes are backported to older versions only in exceptional circumstances.

  • 针对其他编译器进行检查(如果相关)。Checked against other compilers if relevant. 在可能的情况下,涉及可移植 C++ 代码的重现,应在其他编译器中验证行为。Repros that involve portable C++ code should verify behavior against other compilers if possible. 程序的正确性最终由标准来决定,没有完美的编译器,但如果 Clang 和 GCC 接受了代码并且没有诊断,而 MSVC 拒绝,那么我们的编译器可能存在 Bug。The Standard ultimately determines program correctness, and no compiler is perfect, but when Clang and GCC accept your code without a diagnostic and MSVC does not, it's likely you're looking at a bug in our compiler. (其他可能性包括 Unix 和 Windows 行为的差异,或者 C++ 标准实现的级别不同等。)另一方面,如果所有编译器都拒绝代码,则可能是代码不正确。(Other possibilities include differences in Unix and Windows behavior, or different levels of C++ standards implementation, and so on.) On the other hand, if all the compilers reject your code, then it's likely that your code is incorrect. 查看不同的错误消息可能有助于自行诊断问题。Seeing different error messages may help you diagnose the issue yourself.

    你可以在 ISO C++ 网站上的在线C++编译器中找到在线编译器列表,或查看 GitHub 上的在线C ++ 编译器列表,针对这些编译器来测试代码。You can find lists of online compilers to test your code against in Online C++ compilers on the ISO C++ website, or this curated List of Online C++ Compilers on GitHub. 一些具体示例包括 WandboxCompiler ExplorerColiruSome specific examples include Wandbox, Compiler Explorer, and Coliru.

    备注

    在线编译器网站不隶属于 Microsoft。The online compiler websites are not affiliated with Microsoft. 许多在线编译器网站都是作为个人项目运行的,在读到本文时,其中某些网站可能已失效,但通过搜索应该能找到其他可用网站。Many online compiler websites are run as personal projects, and some of these sites may not be available when you read this, but a search should find others you can use.

编译器、链接器和库中的问题往往以特定的方式显示。Problems in the compiler, linker, and in the libraries, tend to show themselves in particular ways. 所遇问题的类型决定了应在报告中添加的重现类型。The kind of problem you encounter will determine what kind of repro you should include in your report. 如果无法正确重新,我们将无法进行调查。Without an appropriate repro, we have nothing to investigate. 以下是你可能会看到的一些类型的问题,以及生成用于报告各类问题的重现的说明。Here are a few of the kinds of issues that you may see, and instructions for generating the kinds of repros you should use to report each kind of problems.

前端(分析程序)故障Frontend (parser) crash

前端故障发生在编译器的分析阶段。Frontend crashes occur during the parsing phase of the compiler. 通常情况下,编译器会发出错误 C1001,并引用错误发生处的源代码文件和行号;它还会常常提及文件 msc1.cpp,你可忽略此详细信息。Typically, the compiler will emit Fatal Error C1001 and reference the source code file and line number on which the error occurred; it will often mention a file msc1.cpp, but you can ignore this detail.

对于这种类型的故障,请提供预处理过的重现For this kind of crash, please provide a Preprocessed Repro.

下面是此种故障类型的示例编译器输出:Here's example compiler output for this kind of crash:

SandBoxHost.cpp
d:\o\dev\search\foundation\common\tools\sandbox\managed\managed.h(929):
        fatal error C1001: An internal error has occurred in the compiler.
(compiler file 'msc1.cpp', line 1369)
To work around this problem, try simplifying or changing the program near the
        locations listed above.
Please choose the Technical Support command on the Visual C++
Help menu, or open the Technical Support help file for more information
d:\o\dev\search\foundation\common\tools\sandbox\managed\managed.h(929):
        note: This diagnostic occurred in the compiler generated function
        'void Microsoft::Ceres::Common::Tools::Sandbox::SandBoxedProcess::Dispose(bool)'
Internal Compiler Error in d:\o\dev\otools\bin\x64\cl.exe.  You will be prompted
        to send an error report to Microsoft later.
INTERNAL COMPILER ERROR in 'd:\o\dev\otools\bin\x64\cl.exe'
    Please choose the Technical Support command on the Visual C++
    Help menu, or open the Technical Support help file for more information

后端(代码生成)故障Backend (code generation) crash

后端故障发生在编译器的代码生成阶段。Backend crashes occur during the code generation phase of the compiler. 通常情况下,编译器会发出错误 C1001,并且可能不会引用与问题相关的源代码文件和行号;它通常会提及文件 compiler\utc\src\p2\main.c,你可以忽略此详细信息。Typically, the compiler will emit Fatal Error C1001, and might not reference the source code file and line number associated with the problem; it will often mention the file compiler\utc\src\p2\main.c, but you can ignore this detail.

对于这种类型的故障,如果使用通过 cl.exe 的 /GL 命令行参数启用的链接时间代码生成 (LTCG),请提供链接重现For this kind of crash, please provide a Link repro if you are using Link-Time Code Generation (LTCG), enabled by the /GL command-line argument to cl.exe. 如果未使用,请提供预处理过的重现If not, please provide a Preprocessed repro instead.

下面是后端故障的示例编译器输出,其中未使用 LTCG。Here's example compiler output for a backend crash in which LTCG is not used. 如果编译器输出与此类似,请提供预处理过的重现If your compiler output looks like this you should provide a Preprocessed Repro.

repro.cpp
\\officefile\public\tadg\vc14\comperror\repro.cpp(13) : fatal error C1001:
        An internal error has occurred in the compiler.
(compiler file 'f:\dd\vctools\compiler\utc\src\p2\main.c', line 230)
To work around this problem, try simplifying or changing the program near the
        locations listed above.
Please choose the Technical Support command on the Visual C++
Help menu, or open the Technical Support help file for more information
INTERNAL COMPILER ERROR in
        'C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\cl.exe'
    Please choose the Technical Support command on the Visual C++
    Help menu, or open the Technical Support help file for more information

如果以内部编译器错误开头的行提及 link.exe,而不是 cl.exe 并且已启用 LTCG,请提供链接重现If the line that begins with INTERNAL COMPILER ERROR mentions link.exe, rather than cl.exe, LTCG was enabled and you should provide a Link Repro. 如果不清楚是否因编译器错误消息而启用了 LTCG,可能需要检查你在 /GL 命令行参数的上一步中,从生成日志复制的命令行参数。If its not clear whether LTCG was enabled from the compiler error message, you may need to examine the command line arguments that you copied from your build log in a previous step for the /GL command-line argument.

链接器故障Linker crash

链接器故障发生在链接阶段,在编译器已运行之后。Linker crashes occur during the linking phase, after the compiler has run. 通常情况下,链接器将发出链接器工具错误 LNK1000Typically, the linker will emit Linker Tools Error LNK1000.

备注

如果输出提及 C1001 或涉及链接时间代码生成,请参阅后端(代码生成)故障,了解更多信息。If the output mentions C1001 or involves Link-Time Code Generation, refer to Backend (code generation) crash instead for more information.

对于这种类型的故障,请提供链接重现For this kind of crash, please provide a Link repro.

下面是此种故障类型的示例编译器输出。Here's example compiler output for this kind of crash.

z:\foo.obj : error LNK1000: Internal error during IMAGE::Pass2

  Version 14.00.22816.0

  ExceptionCode            = C0000005
  ExceptionFlags           = 00000000
  ExceptionAddress         = 00007FF73C9ED0E6 (00007FF73C9E0000)
        "z:\tools\bin\x64\link.exe"
  NumberParameters         = 00000002
  ExceptionInformation[ 0] = 0000000000000000
  ExceptionInformation[ 1] = FFFFFFFFFFFFFFFF

CONTEXT:

  Rax    = 0000000000000400  R8     = 0000000000000000
  Rbx    = 000000655DF82580  R9     = 00007FF840D2E490
  Rcx    = 005C006B006F006F  R10    = 000000655F97E690
  Rdx    = 000000655F97E270  R11    = 0000000000000400
  Rsp    = 000000655F97E248  R12    = 0000000000000000
  Rbp    = 000000655F97EFB0  E13    = 0000000000000000
  Rsi    = 000000655DF82580  R14    = 000000655F97F390
  Rdi    = 0000000000000000  R15    = 0000000000000000
  Rip    = 00007FF73C9ED0E6  EFlags = 0000000000010206
  SegCs  = 0000000000000033  SegDs  = 000000000000002B
  SegSs  = 000000000000002B  SegEs  = 000000000000002B
  SegFs  = 0000000000000053  SegGs  = 000000000000002B
  Dr0    = 0000000000000000  Dr3    = 0000000000000000
  Dr1    = 0000000000000000  Dr6    = 0000000000000000
  Dr2    = 0000000000000000  Dr7    = 0000000000000000

如果启用了增量链接,且仅在进行成功地初始链接之后才发生故障(也就是说,仅在第一个完整链接之后才发生,随后的增量链接都基于该完整链接),请提供对象 (.obj) 和库 (.lib) 文件的副本,它们对应于初始链接完成后经过修改的源文件。If incremental linking is enabled and the crash occurred only after a successful initial link, (that is, only after the first full linking on which subsequent incremental linking is based) please also provide a copy of the object (.obj) and library (.lib) files that correspond to source files that were modified after the initial link was completed.

错误代码生成Bad code generation

错误代码生成很少发生,但当编译器错误地生成不正确的代码时,它将发生,并造成应用程序在运行时(而非在编译时检测此问题时)出现故障。Bad code generation is rare, but occurs when the compiler mistakenly generates incorrect code that will cause your application to crash at runtime rather than detecting this problem at compile-time. 如果你认为所遇到的问题会导致错误代码生成,请将报告同样视为后端(代码生成)故障If you believe the problem you are experiencing results in bad code generation, treat your report the same as a Backend (code generation) crash.

对于这种类型的故障,如果使用通过 cl.exe 的 /GL 命令行参数启用的链接时间代码生成 (LTCG),请提供链接重现For this kind of crash please provide a Link repro if you are using Link-Time Code Generation (LTCG), enabled by the /GL command-line argument to cl.exe. 如果未使用,请提供预处理过的重现Please provide a Preprocessed repro if not.

如何生成重现How to generate a repro

高质量重现对于帮助我们跟踪问题的根源至关重要。To help us track down the source of the problem, a good repro is vital. 在针对特定类型的重现执行以下任何步骤之前,请尝试尽可能减少用于说明问题的代码。Before you do any of the steps outlined below for specific kinds of repros, try to condense the code that demonstrates the problem as much as possible. 尝试删除或最大程度减少依赖项、所需的标头和库,并尽可能限制使用的编译器选项和预处理器定义。Try to eliminate or minimize dependencies, required headers, and libraries, and limit the compiler options and preprocessor definitions used if possible.

以下是生成用于报告不同类型问题的各种重现的说明。Below are instructions for generating the various kinds of repros you'll use to report different kinds of problems.

预处理过的重现Preprocessed repros

预处理过的重现是用于说明问题的单个源文件,通过在原始重现源文件中使用 /P 编译器选项,基于 C 预处理器的输出生成。A preprocessed repro is a single source file that demonstrates a problem, generated from the output of the C preprocessor by using the /P compiler option on the original repro source file. 此内联包含标头,以删除其他源和头文件中的依赖项、宏、#ifdefs 以及其他可能依赖本地化环境的预处理器命令。This inlines included headers to remove dependencies on additional source and header files, and also resolves macros, #ifdefs, and other preprocessor commands that could depend your local environment.

备注

对于在标准库实现中可能导致 Bug 的问题,预处理过的重现可能不是很有用,因为我们经常会替换正在进行的最新实现,以确定我们是否已修复问题。Preprocessed repros are not as useful for problems that might be the result of bugs in our standard library implementation, because we will often want to substitute our latest, in-progress implementation to see whether we've already fixed the problem. 在这种情况下,请勿预处理重现,此外,如果无法将问题减少为单个源文件,请将代码打包为 .zip 文件或类似文件,或考虑使用 IDE 项目重现。In this case, don't preprocess the repro, and if you can't reduce the problem to a single source file, package your code into a .zip file or similar, or consider using an IDE project repro. 有关详细信息,请参阅其他重现For more information, see Other repros.

预处理源代码文件To preprocess a source code file

  1. 捕获用于生成重现的命令行参数,如报告命令行的内容中所述。Capture the command line arguments used to build your repro, as described in To report the contents of the command line.

  2. 打开与用于生成项目的 Visual Studio 版本和配置体系结构匹配的“开发人员命令提示”。Open the Developer Command Prompt that matches the Visual Studio version and configuration architecture used to build your project.

  3. 转到包含重现项目的目录。Change to the directory that contains your repro project.

  4. 在开发人员命令提示控制台窗口中,输入命令 cl /P arguments filename.cpp,其中 arguments 是前面捕获的参数列表,filename.cpp 是重现源文件的名称。In the developer command prompt console window, enter the command cl /P arguments filename.cpp, where arguments is the list of arguments captured above, and filename.cpp is the name of your repro source file. 此命令复制用于重现的命令行,但在预处理器传递后停止编译,并将预处理过的源代码输出到 filename.i。This command replicates the command line used for the repro, but stops the compilation after the preprocessor pass, and outputs the preprocessed source code to filename.i.

如果正在预处理 C++/CX 源代码文件,或正在使用 C++ 模块功能,则需执行一些额外步骤。If you are preprocessing a C++/CX source code file, or you are using the C++ Modules feature, some additional steps are required. 有关详细信息,请参见下方内容。For more information, see the sections below.

如果已生成了预处理过的文件,最好确保仍可使用该预处理过的文件来重现问题。After you have generated the preprocessed file, its a good idea to make sure that the problem still repros using the preprocessed file.

确认仍可以通过预处理过的文件来重现错误To confirm that the error still repros with the preprocessed file

  1. 在“开发人员命令提示”控制台窗口中,输入命令 cl arguments /TP filename.i,告知 cl.exe 将预处理过的文件编译为 C++ 源文件,其中 arguments 是前面捕获的参数列表,但删除了 /D 和 /I 参数(因为它们已包含在预处理过的文件中);filename.i 是预处理过的文件的名称。In the developer command prompt console window, enter the command cl arguments /TP filename.i to tell cl.exe to compile the preprocessed file as a C++ source file, where arguments is the list of arguments captured above, but with any /D and /I arguments removed (because they have already been included in the preprocessed file); and where filename.i is the name of your preprocessed file.

  2. 确认该问题可被重现。Confirm that the problem is reproduced.

最后,将预处理过的重现 filename.i 附加到报告中。Finally, attach the preprocessed repro filename.i to your report.

预处理过的 C++/CX WinRT/UWP 代码重现Preprocessed C++/CX WinRT/UWP code repros

如果使用 C++/CX 生成可执行文件,则需执行一些额外步骤来创建和验证预处理过的重现。If you're using C++/CX to build your executable, there are some extra steps required to create and validate a preprocessed repro.

预处理 C++/CX 源代码To preprocess C++/CX source code

  1. 预处理源代码文件的介绍创建一个预处理过的源代码文件。Create a preprocessed source file as described in To preprocess a source code file.

  2. 在生成的 filename.i 文件中搜索 #using 指令。Search the generated filename.i file for #using directives.

  3. 列出所有参考文件。Make a list of all of the referenced files. 省去所有 Windows*.winmd 文件、platform.winmd 文件和 mscorlib.dll。Leave out any Windows*.winmd files, platform.winmd files, and mscorlib.dll.

准备验证预处理过的文件是否仍然会出现该问题To prepare to validate that the preprocessed file still reproduces the problem,

  1. 为预处理过的文件创建一个新目录并将其复制到新目录。Create a new directory for the preprocessed file and copy it to the new directory.

  2. 将 #using 列表中的 .winmd 文件复制到新目录。Copy the .winmd files from your #using list to the new directory.

  3. 在新目录中创建一个空 vccorlib.h 文件。Create an empty vccorlib.h file in the new directory.

  4. 编辑预处理过的文件,删除 mscorlib.dll 的所有 #using 指令。Edit the preprocessed file to remove any #using directives for mscorlib.dll.

  5. 编辑预处理过的文件,将所有绝对路径更改为复制的 .winmd 文件的文件名。Edit the preprocessed file to change any absolute paths to just the bare filenames for the copied .winmd files.

如上所述,确认预处理过的文件是否仍然会出现该问题。Confirm that the preprocessed file still reproduces the problem, as above.

预处理过的 C++ 模块重现Preprocessed C++ Modules repros

如果正在使用 C++ 编译器的模块功能,则需执行一些不同的步骤来创建和验证预处理过的重现。If you're using the Modules feature of the C++ compiler, there are some different steps required to create and validate a preprocessed repro.

预处理使用模块的源代码文件To preprocess a source code file that uses a module

  1. 捕获用于生成重现的命令行参数,如报告命令行的内容中所述。Capture the command line arguments used to build your repro, as described in To report the contents of the command line.

  2. 打开与用于生成项目的 Visual Studio 版本和配置体系结构匹配的“开发人员命令提示”。Open the Developer Command Prompt that matches the Visual Studio version and configuration architecture used to build your project.

  3. 转到包含重现项目的目录。Change to the directory that contains your repro project.

  4. 在“开发人员命令提示”控制台窗口中,输入命令 cl /P arguments filename.cpp,其中 arguments 是前面捕获的参数列表,filename.cpp 是使用模块的源文件的名称。In the developer command prompt console window, enter the command cl /P arguments filename.cpp, where arguments is the list of arguments captured above, and filename.cpp is the name of the source file that consumes the module.

  5. 更改为包含用于生成模块接口(.ifc 输出)的重现项目的目录。Change to the directory that contains the repro project that built the module interface (the .ifc output).

  6. 捕获用于生成模块接口的命令行参数。Capture the command line arguments used to build your module interface.

  7. 在“开发人员命令提示”控制台窗口中,输入命令 cl /P arguments modulename.ixx,其中 arguments 是前面捕获的参数列表,modulename.ixx 是创建模块接口的文件的名称。In the developer command prompt console window, enter the command cl /P arguments modulename.ixx, where arguments is the list of arguments captured above, and modulename.ixx is the name of the file that creates the module interface.

如果已生成了预处理过的文件,最好确保仍可使用该预处理过的文件来重现问题。After you have generated the preprocessed files, its a good idea to make sure the problem still repros using the preprocessed file.

确认仍可以通过预处理过的文件来重现错误To confirm that the error still repros with the preprocessed file

  1. 在开发人员控制台窗口中,转回包含重现项目的目录。In the developer console window, change back to the directory that contains your repro project.

  2. 输入上述命令 cl arguments /TP filename.i,将预处理过的文件视为 C++ 源文件进行编译。Enter the command cl arguments /TP filename.i as above, to compile the preprocessed file as if it were a C++ source file.

  3. 确认预处理过的文件是否仍然会出现该问题。Confirm that the problem is still reproduced by the preprocessed file.

最后,将预处理过的重现文件(filename.i 和 modulename.i)与 .ifc 输出一起附加到报告中。Finally, attach the preprocessed repro files (filename.i and modulename.i) along with the .ifc output to your report.

链接重现是链接器生成的内容,该内容是 link_repro 环境变量指定的目录的内容。A link repro is the linker-generated contents of a directory specified by the link_repro environment variable. 它包含一些生成项目,这些项目共同说明链接时出现的问题,例如涉及链接时间代码生成 (LTCG) 的后端故障或链接器故障。It contains build artifacts that collectively demonstrate a problem that occurs at link time, such as a backend crash involving Link-Time Code Generation (LTCG), or a linker crash. 需要将这些生成项目用作链接器输入,以便重现问题。These build artifacts are the ones needed as linker input so that the problem can be reproduced. 通过使用此环境变量实现链接器的内置重现生成功能,可以轻松创建链接重现。A link repro can be created easily by using this environment variable to enable the built-in repro generation capability of the linker.

  1. 捕获用于生成重现的命令行参数,如报告命令行的内容中所述。Capture the command line arguments used to build your repro, as described in To report the contents of the command line.

  2. 打开与用于生成项目的 Visual Studio 版本和配置体系结构匹配的“开发人员命令提示”。Open the Developer Command Prompt that matches the Visual Studio version and configuration architecture used to build your project.

  3. 在开发人员命令提示控制台窗口中,转到包含重现项目的目录。In the developer command prompt console window, change to the directory that contains your repro project.

  4. 输入 mkdir linkrepro,创建链接重现的目录。Enter mkdir linkrepro to create a directory for the link repro.

  5. 输入命令 set link_repro=linkrepro,将 link_repro 环境变量设置为刚刚创建的目录。Enter the command set link_repro=linkrepro to set the link_repro environment variable to the directory you just created.

  6. 要在 Visual Studio 中生成重现项目,请在开发人员命令提示控制台窗口中输入命令 devenv。To build the repro project in Visual Studio, in the developer command prompt console window, enter the command devenv. 这可确保 link_repro 环境变量的值对 Visual Studio 可见。This ensures that the value of the link_repro environment variable is visible to Visual Studio. 要在命令行生成项目,请使用前面捕获的命令行参数来复制重现生成。To build the project at the command line, use the command line arguments captured above to duplicate the repro build.

  7. 生成重现项目,并确认预期问题已发生。Build your repro project, and confirm that the expected problem has occurred.

  8. 如果使用了 Visual Studio 执行生成,请将其关闭。Close Visual Studio if you used it to perform the build.

  9. 在开发人员命令提示控制台窗口中,输入命令 set link_repro=,清除 link_repro 环境变量。In the developer command prompt console window, enter the command set link_repro= to clear the link_repro environment variable.

最后,通过将整个 linkrepro 目录压缩为 .zip 文件或类似的文件来打包重现,并将其附加到报告中。Finally, package the repro by compressing the entire linkrepro directory into a .zip file or similar and attach it to your report.

其他重现Other repros

如果无法将问题减少为单个源文件或预处理过的重现,且此问题无需链接重现,我们可以调查 IDE 项目。If you can't reduce the problem to a single source file or preprocessed repro, and the problem does not require a link repro, we can investigate an IDE project. 所有关于如何创建高质量重现的说明仍然适用;代码应最精简且自包含,问题应发生在我们最新的工具中,并且如果相关,该问题不应该在其他编译器中出现。All the guidance on how to create a good repro still applies; the code should be minimal and self-contained, the problem should occur in our most recent tools, and if relevant, the problem should not be seen in other compilers.

将重现创建为一个最小的 IDE 项目,再将整个目录结构压缩成 .zip 文件或其他相似文件,并将其附加到报告。Create your repro as a minimal IDE project, then package it by compressing the entire directory structure into a .zip file or similar and attach it to your report.

发送报告的方式Ways to send your report

可通过多种方式向我们提交报表。There are a couple of good ways to get your report to us. 可使用 Visual Studio 的内置“报告问题”工具Visual Studio 开发者社区页面。You can use Visual Studio's built-in Report a Problem Tool, or the Visual Studio Developer Community pages. 还可通过选择此页底部的“产品反馈”按钮直接进入开发人员社区页面。You can also get directly to our Developer Community pages by choosing the Product feedback button at the bottom of this page. 此选择取决于你是想使用 IDE 中的内置工具来捕获屏幕截图和组织报告以在开发人员社区页中进行发布,还是想直接使用网页。The choice depends on whether you want to use the tools built into the IDE for capturing screenshots and organizing your report for posting on the Developer Community pages, or if you'd prefer to use the website directly.

备注

无论以何种方式提交报告,Microsoft 都尊重你的隐私。Regardless of how you submit your report, Microsoft respects your privacy. Microsoft 致力于遵守所有数据隐私法律和法规。Microsoft is committed to compliance with all data privacy laws and regulations. 有关我们如何处理你发送给我们的数据的信息,请参阅 Microsoft 隐私声明For information about how we treat the data that you send us, see the Microsoft Privacy Statement.

使用“报告问题”工具Use the Report a Problem tool

Visual Studio 用户可使用 Visual Studio 中的“报告问题”工具报告各种问题,单击几下即可完成。The Report a Problem tool in Visual Studio is a way for Visual Studio users to report a variety of problems with just a few clicks. 该工具提供了一个简单的表单,你可以使用它来指定所遇问题的详细信息,然后在不离开 IED 的情况下提交报告。It provides a simple form that you can use to specify detailed information about the problem you've encountered and then submit your report without ever leaving the IDE.

可在 IDE 中使用“报告问题”工具快速而轻松地报告问题。Reporting your problem through the Report a Problem tool is easy and convenient from the IDE. 可选择“快速启动”搜索框旁边的“发送反馈”图标,从标题栏中进行访问,也可通过“帮助” > “发送反馈” > “报告问题”在菜单栏上找到它。You can access it from the title bar by choosing the Send Feedback icon next to the Quick Launch search box, or you can find it on the menu bar in Help > Send Feedback > Report a Problem.

选择报告问题时,请首先在开发者社区中搜索是否有类似的问题。When you choose to report a problem, first search the Developer Community for similar problems. 如果有人之前已报告过你的问题,可投票赞成该主题并添加其他细节评论。If your problem has been reported before, upvote the topic and add comments with additional specifics. 如果找不到类似问题,请在“Visual Studio 反馈”对话框底部选择“报告新问题”按钮,再按照步骤报告你的问题。If you don't see a similar problem, choose the Report new problem button at the bottom of the Visual Studio Feedback dialog and follow the steps to report your problem.

使用“Visual Studio 开发者社区”页面Use the Visual Studio Developer Community pages

还可使用“Visual Studio 开发者社区”页面轻松报告问题并查找有关 Visual Studio 以及 C++ 编译器、工具和库的解决方案。The Visual Studio Developer Community pages are another convenient way to report problems and find solutions for Visual Studio, the C++ compiler, tools, and libraries. 可使用 Visual Studio 问题页面报告有关 IDE 或安装的问题。The Visual Studio Questions page is where to report problems with the IDE or installation. 有关 C++ 编译器、链接器及其他工具和库的相关问题,请使用 C++ 问题页面。For issues with the C++ compiler, linker, and other tools and libraries, use the C++ Questions page.

在每页顶部附近的“开发者社区”横幅中有一个搜索框,可用于查找报告了与你问题相似的问题的帖子或主题。In the Developer Community banner near the top of each page is a search box you can use to find posts or topics that report problems similar to yours. 你可能发现现有主题中已存在解决方案或与你问题相关的其他有用信息。You may find that a solution or other useful information related to your problem is already available in an existing topic. 如果有人之前已报告过相同问题,请投票赞成该主题并进行评论,而不是创建新的问题报告。If someone has reported the same problem before, please upvote and comment on that topic rather than create a new problem report.

如果之前无人报告你的问题,请选择“开发者社区”页面上搜索框附近的“报告问题”按钮。If your problem has not been reported before, choose the Report a problem button next to the search box on the Developer Community page. 系统可能要求你登录 Visual Studio 帐户并同意开发者社区应用访问你的个人资料。You may be asked to sign in to your Visual Studio account and to agree to give the Developer Community app access to your profile. 登录后,将直接转到可报告问题的页面。When you are signed in, you go directly to a page where you can report the problem. 可附上重现代码和命令行、屏幕截图、相关讨论的链接,以及你认为相关和有用的任何其他信息。You can include your repro code and command line, screen shots, links to related discussions, and any other information you think is relevant and useful.

提示

对于可能在 Visual Studio 中遇到的、与工具集无关的问题(例如 UI 问题、损坏的 IDE 功能或常规故障),“报告问题工具”可能是最佳之选,因为它具有屏幕截图功能,可以记录导致问题的 UI 操作。For other kinds of problems you might encounter in Visual Studio that are not related to the toolset (For example, UI issues, broken IDE functionality, or general crashes), the Report a Problem tool can be an especially good choice due to its screenshot capabilities and its ability to record UI actions that lead to the problem you've encountered. 还可在开发人员社区站点报告这些错误。These kinds of errors can also be reported on the Developer Community site.

报表和隐私Reports and privacy

默认情况下,报告中的所有信息、评论和回复都是公开可见的。By default, all information in reports and any comments and replies are publicly visible. 一般来说,这是有好处的,因为这样整个社区都能看到其他用户发现的问题、解决方案和解决方法。Normally, this is a benefit, because it allows the entire community to see the issues, solutions, and workarounds other users have found. 但是,如果担心数据或身份公开后会出现隐私或知识产权问题,则可另作选择。However, if you're concerned about making your data or identity public, for privacy or intellectual property reasons, you have options.

如果担心身份泄露,请创建一个新 Microsoft 帐户,该帐户不会透露任何详细信息。If you are concerned about revealing your identity, create a new Microsoft account that does not disclose any details about you. 使用此帐户来创建报表。Use this account to create your report.

不要在初始报表标题或内容中添加任何想要保密的内容,因为这会被公开。Don't put anything you want to keep private in the title or content of the initial report, which is public. 相反,请注意,将通过单独的评注以私密方式发送详细信息。Instead, note that you will send details privately in a separate comment. 为确保报表发送给正确的人员,请在问题报表的主题列表中加入 cppcompiler。To make sure that your report is directed to the right people, include cppcompiler in the topic list of your problem report. 创建问题报表后便可指定谁可以查看回复和附件。Once the problem report is created, it's now possible to specify who can see your replies and attachments.

创建私人信息问题报表To create a problem report for private information

  1. 在创建的报表中,选择“添加注释”,创建对问题的私人说明。In the report you created, choose Add comment to create your private description of the problem.

  2. 在回复编辑器中,使用“提交”和“取消”按钮下的下拉控件,指定可查看回复的群体。In the reply editor, use the dropdown control below the Submit and Cancel buttons to specify the audience for your reply. 只有指定的人员能看到这些私人回复以及其中的图像、链接或代码。Only the people you specify can see these private replies and any images, links, or code you include in them. 选择“版主和贴主可见”,可仅允许 Microsoft 员工和自己查看。Choose Viewable by moderators and the original poster to limit visibility to Microsoft employees and yourself.

  3. 添加重现所需的说明和所有其他信息、图像和文件附件。Add the description and any other information, images, and file attachments needed for your repro. 选择“提交”按钮将私下发送此信息。Choose the Submit button to send this information privately.

    请注意,附件大小不得超过 2GB,最多可附加 10 个文件。Note that there is a 2GB limit on attached files, and a maximum of 10 files. 若要上传更大容量的内容,请在私人评论中申请获取上传网址。For any larger uploads, please request an upload URL in your private comment.

同样,只有指定的人员能查看此注释下的所有回复。Any replies under this comment have the same restricted visibility you specified. 即使回复上的下拉控件未正确显示可见性受限状态,仍是如此。This is true even if the dropdown control on replies does not show the restricted visibility status correctly.

为了维护你的隐私,不暴露敏感信息,请通过在此受限注释下进行回复与 Microsoft 进行一切沟通。To maintain your privacy and keep your sensitive information out of public view, please take care to keep all interaction with Microsoft to replies under this restricted comment. 回复其他评论可能会导致敏感信息意外泄露。Replies to other comments may cause you to accidentally disclose sensitive information.

如何报告 C++ 文档问题How to report a C++ documentation issue

我们使用 GitHub 问题来跟踪文档中报告的问题。We use GitHub issues to track problems reported in our documentation. 现在可直接从内容页创建 GitHub 问题,这可帮助用户以更丰富的方式与文档作者和产品团队进行互动。You can now create GitHub issues directly from a content page, which enables you interact in a much richer way with writers and product teams. 如果发现文档存在问题、错误代码示例、令人困惑的说明、关键信息的遗漏,甚至只是一个拼写错误,都请与我们联系。If you see an issue with a document, a bad code sample, a confusing explanation, a critical omission, or even just a typo, you can easily let us know. 滚动至本页底部,然后选择“登录以提供文档反馈”。Scroll to the bottom of the page and select Sign in to give documentation feedback. 如果现在没有 GitHub 帐户,则需要创建一个,创建帐户后,可以看到所有文档问题及其状态,还可在报告的问题有了变化时收到通知。You'll need to create a GitHub account if you don't have one already, but once you do, you can see all of our documentation issues, their status, and get notifications when changes are made for the issue you reported. 有关详细信息,请参阅 docs.microsoft.com 中即将推出的新反馈系统For more information, see A New Feedback System Is Coming to docs.microsoft.com.

使用文档反馈按钮在 GitHub 上创建文档问题时,创建问题的页面的相关信息会自动填写到该问题中,这样我们就可了解问题出现的位置。When you create a documentation issue on GitHub by using the documentation feedback button, the issue is automatically filled in with some information about the page you created the issue on, so we know where the problem is located. 请不要编辑该信息。Please don't edit this information. 只需要追加错误的详细信息和建议的修复方法(如果愿意)。Just append the details about what's wrong and, if you like, a suggested fix. 文档为开放源,如果想要自己对其进行实际修复和提出建议,可直接进行。Our documentation is open source, so if you'd like to actually make a fix and propose it yourself, you can do that. 有关帮助改进文档的方式的详细信息,请参阅 GitHub 上的帮助指南For more information about how you can contribute to our documentation, see our Contributing guide on GitHub.