Remote Debugging: "The breakpoint will not currently be hit. No symbols have been loaded for this document."

Problem:

When you are remotely debugging your breakpoints show a message that, "The breakpoint will not currently be hit. No symbols have been loaded for this document."

This post is written for a .NET project where you are debugging on one computer (the local machine) and the code is running in IIS on another server (DevServer in this example).

Solution:

Solution 1 - Ensure that PDB files are being generated for your build

On the remote server, navigate in file explorer to the bin folder for your project. This is usually located on the C: drive in inetpub\wwwroot\TheProject\bin. Ensure that there are .PDB files in this folder. If there are not, go back to Visual Studio and change your project's property's so that generated debug symbols are included.

To do this in Visual Studio 2015: Right click on your project and select Properties. Click "Package/Publish Web". Ensure "Exclude Generated debug symbols" is unchecked. You will most likely want to do this for the Debug and Release Configurations.

If you have done Option 1 and are still getting this error, go to Option 2.

Solution 2 - Ensure that you have the same version of code locally and on the remote server.

Before attaching to a process, look at the size of the DLL and PDB files if they are different sizes you may have slightly different versions. This can happen if the code was built using two different methods. For example if the code locally was built using Visual Studio but the code on the remote server was built with release management.

Go to Tools > Options > debugging > Symbols. Add a new Symbol file location for your build server.
Make it point to the bin folder of the project you want to debug. If you have multiple projects you want to debug, add each of their bin folders. It should look something like the screen shot below.

Now attach your debugger to the remote server and confirm that symbols have loaded for your project.

Solution 3 - Ensure you've attached to the right process

Using your browser, navigate to the website hosted on the remote server. This ensures that the process will be running in IIS. In Visual Studio, in the "Attach to Process..." window, find the w3wp.exe process. If there are multiple, try connecting to all of them, but you should be able to tell which one is the website you want. If your symbols are loaded correctly after trying this, you had the correct DLL and PDB files locally and on the remote server, the problem was that Visual Studio was connecting to the wrong process.

It should look similar to the below screen shot.

Solution 4 - Ensure local and Release Management / MSBuilds are generating identical files.

The other solution would be to modify your release management build to make your local build and release management build have the exact same settings so they generate identical DLL and PDB files. This will not be covered in this post because it is outside the scope of this post. However, see the "Other things to try" section below for instructions on manually copying DLL and PDB files from your local machine to the remote server, which would ensure the local and remote versions are the same. However, that is not a proper solution and should only be used for troubleshooting.

Explanation:

The DLLs and PDBs that are generated from a local build need to match the files on the remote server where the code is running. If they do not, or if the symbol files cannot be located by Visual Studio, this error will show up on your breakpoints.

Sometimes you'll build your project in Visual Studio and build that same project with release management or MSBuild, but the DLL and PDB files are different. This can be due to a difference in the build configurations for Visual Studio and release management.

Other things to try:

Manually copy DLL and PDB files from local machine to remote server.

Build the project on your local machine, make sure symbol files (.pdb) are included. To get these symbol files try building in Debug mode. If you still don't have symbol files, right click your project file, and under Package/Publish Web uncheck "Exclude generated debug symbols".
Now find you're project's bin folder in explorer. You should have a fresh set of DLL and PDB files in this folder. The "Date Modified" for any DLL and its matching PDB file should be about the same.

Now find the bin folder for this project on the remote server. It should be the same as what you added to the symbol file locations, so in our example it's \\DevServer\c$\inetpub\wwwroot\TheProject\bin.
Create a backup of this folder just for safe keeping.

Now overwrite the bin folder on the server by copying the bin folder from your local computer to the remote server. The purpose of this is to ensure you have the exact same files locally and on the remote server. This is not a good permanent solution, but if your breakpoints get hit now it proves that your remote debugging is configured mostly correctly and that the problem is a difference with the DLL and PDB files between your local machine and the remote server.

Symbol Status

While debugging, in Visual Studio go to Debug > Windows > Modules. This window can provide you with lots of information for troubleshooting. Look for the DLL of your project (TheProject.dll in our examples). If the Symbol Status shows "Symbols loaded." then things are working correctly.

You can right click on an entry here and click "Load Symbols" to point to a symbol file to use. If Visual Studio likes the symbol files you selected, the symbols will load and the error will go away.

Further Reading

https://blogs.msdn.microsoft.com/visualstudioalm/2015/01/05/understanding-symbol-files-and-visual-studios-symbol-settings/