Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update debugging-runtime.md #106518

Merged
merged 5 commits into from
Aug 16, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions docs/workflow/debugging/coreclr/debugging-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,15 +223,19 @@ Native C++ code is not everything in our runtime. Nowadays, there are lots of st

#### Resolving Signature Validation Errors in Visual Studio

Starting with Visual Studio 2022 version 17.5, Visual Studio will validate that the debugging libraries that shipped with the .NET Runtime are correctly signed before loading them. If they are unsigned, Visual Studio will show an error like:
Visual Studio 2022 version 17.5 and later validates that the debugging libraries shipped with the .NET Runtime are signed before loading them. If they are unsigned, Visual Studio shows an error similar to the following:

> Unable to attach to CoreCLR. Signature validation failed for a .NET Runtime Debugger library because the file is unsigned.
>
> This error is expected if you are working with non-official releases of .NET (example: daily builds from https://github.com/dotnet/sdk). See https://aka.ms/vs/unsigned-dotnet-debugger-lib for more information.

If the target process is using a .NET Runtime that is either from a daily build, or one that you built on your own computer, this error will show up. **NOTE**: This error should never happen for official builds of the .NET Runtime from Microsoft. So don’t disable the validation if you expect to be using a .NET Runtime supported by Microsoft.
This error occurs if the target process is using a daily build .NET Runtime or one that you built. **NOTE**: This error never happens with [released builds of the .NET Runtime from Microsoft](https://dotnet.microsoft.com/en-us/download/dotnet). ***Don’t*** disable the validation if you are using an official release of the .NET Runtime.

There are three ways to configure Visual Studio to disable signature validation:
1. The [`DOTNET_ROOT` environment variable](https://learn.microsoft.com/dotnet/core/tools/dotnet-environment-variables#dotnet_root-dotnet_rootx86): if Visual Studio is started from a command prompt where `DOTNET_ROOT` is set, it will ignore unsigned .NET runtime debugger libraries which are under the `DOTNET_ROOT` directory.
2. The `VSDebugger_ValidateDotnetDebugLibSignatures` environment variable: If you want to temporarily disable signature validation, run `set VSDebugger_ValidateDotnetDebugLibSignatures=0` in a command prompt, and start Visual Studio (devenv.exe) from this command prompt.
3. Set the `ValidateDotnetDebugLibSignatures` registry key: To disable signature validation on a more permanent basis, you can set the VS registry key to turn it off. To do so, open a Developer Command Prompt, and run `Common7\IDE\VsRegEdit.exe set local HKCU Debugger\EngineSwitches ValidateDotnetDebugLibSignatures dword 0`
The following approaches configure Visual Studio to disable signature validation:

1. The `VSDebugger_ValidateDotnetDebugLibSignatures` environment variable:
* This is the easiest and recommended approach to temporarily disable signature validation.
* At the command line, run `set VSDebugger_ValidateDotnetDebugLibSignatures=0` and then start Visual Studio (`devenv.exe`) from the same command prompt.
* This setting is only valid for the Visual Studio instance that is started from the command prompt where the environment variable is set.
1. The [`DOTNET_ROOT` environment variable](https://learn.microsoft.com/dotnet/core/tools/dotnet-environment-variables#dotnet_root-dotnet_rootx86): if Visual Studio is started from a command prompt where `DOTNET_ROOT` is set, it ignores unsigned .NET runtime debugger libraries which are under the `DOTNET_ROOT` directory.
1. ***NOT RECOMMENDED*** Set the `ValidateDotnetDebugLibSignatures` registry key: To disable signature validation on a more permanent basis, set the `Common7\IDE\VsRegEdit.exe set local HKCU Debugger\EngineSwitches ValidateDotnetDebugLibSignatures dword 0` VS registry key. For example, open a Developer Command Prompt and run `Common7\IDE\VsRegEdit.exe set local HKCU Debugger\EngineSwitches ValidateDotnetDebugLibSignatures dword 0`