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

如果发现 Microsoft C++ 编译器 (MSVC)、链接器或其他工具和库的问题,请告诉我们。If you find problems in the Microsoft C++ compiler (MSVC), the linker, or other tools and libraries, we want to know about them. 文档中存在问题时,我们也想要了解。When 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 discovered. 它应包含有关如何生成程序的所有详细信息。It should have all the details about how you build your program. 而且它应包括“重现” ,即我们可在我们自己的计算机上重现该问题的完整测试用例。And it should include 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 isn't local to your environment. 它可帮助我们确定是否会影响编译器的其他版本,并诊断其原因。It helps us 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. 我们将描述如何生成所发现问题类型的重现,以及如何将报告发送给产品团队。We describe 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. 谢谢你帮助我们改进 Microsoft C++!Thank you for helping us improve Microsoft C++!

如何准备报告How to prepare your report

最好创建高质量报告,因为如果缺少完整信息,很难重现你发现的问题。It's important to create a high-quality report, because it's difficult for us to reproduce the problem you found without complete information. 报告的质量越高,我们重新创建和诊断问题的效率就越高。The better your report is, the more effectively we can 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 found.

  • 重现:简单完整的自包含源代码示例,用于演示问题。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. 这样我们就可以针对我们的计算机的相同工具集测试你的重现。That's so 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 have the same problem.

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

  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:

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. 这样我们就可以在我们的计算机上以完全相同的方式生成它。That's so we can build it in exactly the same way on our machines. 这一点很重要,因为你所发现的问题可能仅在使用某一特定参数或参数组合生成时才存在。It's important because the problem you've found 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 you experience the problem. 这可确保命令行包含完全相同的参数,从而有可能帮助解决问题。It ensures that the command line contains exactly the same arguments that might contribute 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've changed the default location for your project.

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

  2. 找到包含出现问题的源代码文件名称的行。Locate the line that contains the name of the source code file where the problem occurs. 其下方的行包含相应的 cl.exe 命令参数。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 found. 这样我们就可以确认在我们的计算机上看到相同的效果。That's so we can verify that we see the same effect on our machines. 让我们了解你尝试完成的内容以及你预期发生的内容有时也非常有用。It's also sometimes useful for us to know what you were trying to accomplish, and what you expected to happen.

好的描述会提供工具集给出的确切错误消息,或者看到的确切运行时行为 。A good description provides 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. 提供所有编译器输出,而不仅仅是最后一个错误消息 。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. 如果可以使用命令行编译器来复制问题,该编译器输出是首选。If you can duplicate the issue by using the command-line compiler, that compiler output is preferred. IDE 和其他生成系统可能会筛选你看到的错误消息,或者仅捕获一条错误消息的第一行。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 doesn't generate a diagnostic, include that in your report.

若要报告运行时行为问题,请提供该程序输出内容的原样副本,和你想要看到的内容 。To report a runtime behavior problem, include an exact copy of what the program prints, and what you expect to see. 理想情况下,它嵌入在输出语句本身中,例如,printf("This should be 5: %d\n", actual_result);Ideally, you'll embed it 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 found, such as any work-arounds you've discovered. 请尝试不在报表的其他部分出现重复信息。Try not to repeat information found elsewhere in your report.

重现The repro

重现 是一个完整的自包含源代码示例。A repro is a complete, self-contained source code example. 它以可重现的方式演示了你发现的问题,并由此得名。It reproducibly demonstrates the problem you've found, 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 basic executable that compiles and runs. 或者,其将 编译和运行(如果不是针对你发现的问题)。Or, that would compile and run, if not for the problem you've found. 重现不是代码片段。A repro isn't a code snippet. 它应具有完整的函数和类,并包含所有必要 #include 指令,即使对于标准标头也是如此。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 found. 重现无需复杂或真实。Repros don't need to be complex or realistic. 它们只需显示符合标准或记录的编译器实现的代码。They only need to show code that conforms to the Standard, or to the documented compiler implementation. 对于缺失的诊断,你的重现应显示不符合的代码。For a missing diagnostic, your repro should show the code that's not conformant. 重现应简明扼要,最好只包含刚好足够演示问题的代码。Simple, to-the-point repros that contain only 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, then do so. 不需要提供有效代码的反例。You don't 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, then 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);), then 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 whenever possible. 或者,使用下一个更新或下一个主要版本的最新预发布版本。Or, use the most recent prerelease version of the next update or next major release. 在旧版本工具集中可能会发现的问题很可能已在新版本中得到修复。Problems you may find in older versions of the toolset have 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. C++ 标准最终确定程序的正确性,没有编译器是完美的。The C++ standard ultimately determines program correctness, and no compiler is perfect. 但是,如果 Clang 和 GCC 接受了代码但没有诊断,但 MSVC 未接受,你可能已经在我们的编译器中发现了一个 bug。However, when Clang and GCC accept your code without a diagnostic, and MSVC doesn't, you've probably found 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.) When 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 ExplorerSome specific examples include Wandbox and Compiler Explorer.

    备注

    在线编译器网站不隶属于 Microsoft。The online compiler websites are not affiliated with Microsoft. 许多在线编译器网站作为个人项目运行。Many online compiler websites are run as personal projects. 当你读取此代码时,其中某些网站可能不可用,但搜索应该能找到可以使用的其他网站。Some of these sites may be unavailable 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 find 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. 我们随附了有关如何生成应用于报告每种问题的重现类型的说明。We include instructions on how to generate the kind of repro you should use to report each kind of problem.

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

前端故障发生在编译器的分析阶段。Frontend crashes occur during the parsing phase of the compiler. 通常情况下,编译器将发出致命错误 C1001,并引用发生错误的源代码文件和行号。Typically, the compiler emits Fatal Error C1001, and references the source code file and line number on which the error occurred. 它经常提到一个名为 msc1.cpp 的文件,但你可以忽略此详细信息。It often mentions a file named msc1.cpp, but you can ignore this detail.

对于这种类型的故障,请提供预处理过的重现For this kind of crash, 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,且可能不会引用与错误相关的源代码文件和行号。Typically, the compiler emits Fatal Error C1001, and it might not reference the source code file and line number associated with the problem. 它通常会提及文件 compiler\utc\src\p2\main.c,但你可以忽略此详细信息。It often mentions the file compiler\utc\src\p2\main.c, but you can ignore this detail.

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

下面是后端故障的示例编译器输出,其中未使用 LTCG。Here's example compiler output for a backend crash in which LTCG isn't used. 如果编译器输出与以下内容类似,请提供预处理过的重现If your compiler output looks like the following, 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. 对于此情况,请提供链接重现Provide a Link repro in this case. 当不清楚是否从编译器错误消息启用了 LTCG 时,请检查命令行参数。When it's not clear whether LTCG was enabled from the compiler error message, examine the command-line arguments. 在 /GL 命令行参数的上一步中,从生成日志复制这些信息。You copied them 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 this kind of crash, provide a Link repro.

下面是此种故障类型的示例编译器输出:Here's an example of 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 link on which a later incremental link is based, also provide a copy of the object (.obj) and library (.lib) files that correspond to source files modified after the initial link was completed.

错误代码生成Bad code generation

生成错误代码的情况很少见。Bad code generation is rare. 它会在当编译器错误地生成会导致应用程序在运行时崩溃的不正确的代码时发生。It occurs when the compiler mistakenly generates incorrect code that causes your application to crash at runtime. 相反,它应生成正确的代码,或在编译时检测到问题。Instead, it should generate correct code, or detect a problem at compile time. 如果你认为所发现的问题会导致错误代码生成,请将报告同样视为后端(代码生成)故障If you believe the problem you've found results in bad code generation, treat your report the same as a Backend (code generation) crash.

对于这种类型的故障,如果使用 cl.exe 的 /GL 命令行参数,请提供链接重现For this kind of crash, provide a Link repro if you're using the /GL command-line argument to cl.exe. 如果未使用,请提供预处理过的重现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. 限制编译器选项和可能使用的预处理器定义。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

预处理过的重现 是单个源文件,用于说明问题。A Preprocessed repro is a single source file that demonstrates a problem. 它是从 C 预处理器的输出生成的。It's generated from the output of the C preprocessor. 若要创建一个预处理过的重现,请在原始重现源文件上使用 /P 编译器选项。To create one, use the /P compiler option on the original repro source file. 此选项内联包含的标头以删除额外的源文件和标头文件上的依赖项。This option inlines the included headers to remove dependencies on additional source and header files. 此选项还可解析宏、#ifdef 条件语句和其他可能依赖于你的本地环境的预处理器命令。The option also resolves macros, #ifdef conditionals, and other preprocessor commands that could depend on 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 。In the developer command prompt console window, enter the command cl /P arguments filename.cpp. 有关自变量 ,请使用之前捕获的自变量列表。For arguments, use the list of arguments you captured above. filename.cpp 是重现源文件的名称。filename.cpp is the name of your repro source file. 此命令复制用于重现的命令行,但在预处理器传递后停止编译。This command replicates the command line you used for the repro, but stops the compilation after the preprocessor pass. 然后将预处理过的源代码输出到 filename.i 。Then it writes the preprocessed source code to filename.i.

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

如果已生成了预处理过的文件,最好确保在你编译预处理过的文件时问题仍可重现。After you've generated the preprocessed file, it's a good idea to make sure that the problem still repros when you compile the preprocessed file.

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

  1. 在“开发人员命令提示”控制台窗口中,输入命令 cl arguments /TP filename.i,指示 cl.exe 将预处理过的文件编译为 C++ 源文件 。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. 此参数 与上文捕获的参数相同,但删除了任何 /D 和 /I 参数。The arguments are the same arguments captured above, but with any /D and /I arguments removed. 这是因为它们已包含在预处理过的文件中。That's because they've already been included in the preprocessed file. filename.i 是预处理过的文件的名称。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 。In the developer command prompt console window, enter the command cl /P arguments filename.cpp. 此参数 与上文捕获的参数相同,filename.cpp 是使用该模块的源文件的名称。The arguments are the 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 。In the developer command prompt console window, enter the command cl /P arguments modulename.ixx. 此参数 与上文捕获的参数相同,modulename.ixx 是创建模块界面的文件的名称。The arguments are the arguments captured above, and modulename.ixx is the name of the file that creates the module interface.

如果已生成了预处理过的文件,最好确保在你使用预处理过的文件时问题仍可重现。After you've generated the preprocessed files, it's a good idea to make sure the problem still repros when you use the preprocessed file.

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

  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 环境变量指定,或指定为 /LINKREPRO 链接器选项的参数 。A link repro is the linker-generated contents of a directory, specified either by the link_repro environment variable, or as an argument to the /LINKREPRO linker option. 它包含共同说明链接时所出现问题的生成项目。It contains build artifacts that collectively demonstrate a problem that occurs at link time. 示例包括涉及链接时间代码生成 (LTCG) 的后端故障或链接器故障。Examples include a backend crash involving Link-Time Code Generation (LTCG), or a linker crash. 需要将这些生成工件用作链接器输入,以便重现问题。These build artifacts are the ones needed as linker input so the problem can be reproduced. 通过使用此环境变量,可以轻松创建链接重现。A link repro can be created easily by using this environment variable. 它可启用链接器的内置重现生成功能。It enables the linker's built-in repro generation capability.

  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,为链接重现创建名为 linkrepro 的目录 。Enter mkdir linkrepro to create a directory named linkrepro for the link repro. 可以使用不同的名称来捕获另一个链接重现。You can use a different name to capture another 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 created. 如果生成从其他目录中运行(更加复杂的项目通常如此),则转而将 ink_repro 设置为链接重现目录的完整路径 。If your build is run from a different directory, as is often the case for more complex projects, then set link_repro to the full path to your link repro directory instead.

  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 可见 。It 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 do 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.

/LINKREPRO 链接器选项与 link_repro 环境变量具有同样的作用 。The /LINKREPRO linker option has the same effect as the link_repro environment variable. 可以使用 /LINKREPROTARGET 选项来为生成的链接重现指定要筛选的名称。You can use the /LINKREPROTARGET option to specify the name to filter on for the generated link repro. 要使用 /LINKREPROTARGET,还必须指定 /OUT 链接器选项 。To use /LINKREPROTARGET, you must also specify the /OUT linker option.

  1. 创建目录以保存链接重现。Create a directory to hold the link repro. 我们将创建的完整目录路径称作 directory-path 。We'll refer to the full directory path you create as directory-path. 如果路径包含空格,请使用双引号。Use double quotes around the path if it includes spaces.

  2. 将 /LINKREPRO:directory-path 命令添加到链接器命令行 。Add the /LINKREPRO:directory-path command to the linker command line. 在 Visual Studio 中,打开项目的“属性页”对话框 。In Visual Studio, open the Property Pages dialog for your project. 选择“配置属性” > “链接器” > “命令行”属性页 。Select the Configuration Properties > Linker > Command Line property page. 在“附加选项”框中输入 /LINKREPRO:directory-path 选项 。Then, enter the /LINKREPRO:directory-path option in the Additional Options box. 选择“确定”以保存更改 。Choose OK to save your changes.

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

最后,通过将整个 directory-path 链接重现目录压缩为 .zip 文件或类似的文件来打包重现,并将其附加到报告中 。Finally, package the repro by compressing the entire directory-path link repro 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 doesn't require a link repro, we can investigate an IDE project. 有关如何创建高质量重现的所有指导仍适用:该代码应该是最小且自包含的。All the guidance on how to create a good repro still applies: The code ought to be minimal and self-contained. 问题应发生在最新的工具中,并且如果相关,不应出现在其他编译器中。The problem should occur in our most recent tools, and if relevant, shouldn't 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

可通过多种方式向我们提交报告。You have 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 page. 还可以使用此页底部的“产品反馈” 按钮。There's also a Product feedback button at the bottom of this page. 选择取决于你是否想要使用 IDE 中的内置工具捕获屏幕快照和组织报告。The choice depends on whether you want to use the built-in tools in the IDE to capture screenshots and organize your report. 如果你不想,可以直接使用开发人员社区网站。If you prefer not to, you can use the Developer Community 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 problems with just a few clicks. 它会弹出一个简单的表单,发送有关你已发现的问题的详细信息。It pops up a simple form to send detailed information about the problem you've found. 然后,无需离开 IDE 即可提交报告。You can 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. 如果有人之前已报告过你的问题,可投票赞成该报告并添加其他细节评论。In case your problem has been reported before, upvote the report 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 and the C++ compiler, tools, and libraries. 有针对 Visual StudioVisual Studio for Mac.NETC++Azure DevOpsAzure DevOps Server 的特定开发者社区页。There are specific Developer Community pages for Visual Studio, Visual Studio for Mac, .NET, C++, Azure DevOps, and Azure DevOps Server.

社区标签下方每个页面顶部附近有一个搜索框。Beneath the community tabs, near the top of each page, is a search box. 可用它查找报告与你的问题类似的文章。You can use it to find posts that report problems similar to yours. 你可能发现你的问题已经有解决方案或相关的其他有用信息。You may find a solution or other useful information related to your problem is already available. 如果有人之前已报告过相同问题,请投票赞成该报告并进行评论,而不是创建新的问题报告。If someone has reported the same problem before, then upvote and comment on that report, rather than create a new problem report. 若要评论、投票或报告新问题,可能要求你登录到你的 Visual Studio 帐户。To comment, vote, or report a new problem, you may be asked to sign in to your Visual Studio account. 第一次登录时,你需要同意授予开发人员社区应用访问你的配置文件的权限。The first time you sign in, you'll have to agree to give the Developer Community app access to your profile.

有关 C++ 编译器、链接器及其他工具和库的相关问题,请首先搜索 C++ 开发者社区页面。For issues with the C++ compiler, linker, and other tools and libraries, first search the C++ Developer Community page. 如果搜索你的问题后发现之前无人报告该问题,请选择搜索框附近的“报告问题” 按钮。If you search for your problem, and it hasn't been reported before, choose the Report a problem button next to the search box. 可附上重现代码和命令行、屏幕截图、相关讨论的链接,以及你认为相关和有用的任何其他信息。You can include your repro code and command line, screenshots, links to related discussions, and any other information you think is relevant and useful.

提示

对于可能会在 Visual Studio 中发现的与 C++ 工具集无关的其他类型问题(例如,UI 问题、IDE 功能损坏或常规故障),请使用 IDE 中的“报告问题” 工具。For other kinds of problems you might find in Visual Studio that are unrelated to the C++ toolset (For example, UI issues, broken IDE functionality, or general crashes), use the Report a Problem tool in the IDE. 这是最佳选择,因为该工具具备屏幕截图功能,并且可以记录导致你所发现的问题的 UI 操作。This is the best choice, due to its screenshot capabilities and its ability to record UI actions that lead to the problem you've found. 还可在 Visual Studio 开发者社区站点查找这些错误。These kinds of errors can also be looked up on the Visual Studio Developer Community site. 有关详细信息,请参阅如何报告 Visual Studio 的问题For more information, see How to report a problem with Visual Studio.

报表和隐私Reports and privacy

默认情况下,报告中的所有信息、评论和回复都是公开可见的All information in reports and any comments and replies are publicly visible by default. 一般来说,这是有好处的,因为这样整个社区都能看到其他用户发现的问题、解决方案和解决方法。Normally, it's 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're concerned about revealing your identity, create a new Microsoft account that doesn't 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, say that you'll 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.

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

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

若要保留隐私并避免公众查看你的敏感信息,请谨慎授权。To maintain your privacy and keep your sensitive information out of public view, be careful. 将与 Microsoft 的所有交互保留在受限制的评论下的回复中。Keep all interaction with Microsoft to replies under the 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 帐户,需要创建一个 GitHub 帐户。You'll need to create a GitHub account if you don't have one already. 有了 GitHub 帐户后,可以看到所有文档问题及其状态。When you have a GitHub account, you can see all of our documentation issues and their status. 对你报告的问题进行更改时,你还会收到通知。You also 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 上创建文档问题。You create a documentation issue on GitHub when you use the documentation feedback button. 将使用有关创建问题的页面的一些信息自动填充此问题。The issue is automatically filled in with some information about the page you created the issue on. 这是我们知道问题所在位置的途径,因此请勿编辑此信息。That's how we know where the problem is located, so don't edit this information. 只需要追加错误的详细信息和建议的修复方法(如果愿意)。Just append the details about what's wrong, and if you like, a suggested fix. C++ docs 是开放源代码,因此,如果你想要自行提交修补程序,可以自行提交。Our C++ docs are open source, so if you'd like to submit a fix yourself, you can. 有关帮助改进文档的方式的详细信息,请参阅 GitHub 上的帮助指南For more information about how you can contribute to our documentation, see our Contributing guide on GitHub.