ReadMe.md Documentation Questions/Clarifications

[mesheets]

I have been trying out GitLink, and it seems to fill a needed role in enabling Symbol Server / Symbol Store integration capabilities when using a Git-based version control repository. In working through this, I have a few questions/clarifications related to the ReadMe.md.

GitLink makes symbol servers obsolete

This would not appear to be universally true; rather, it would seem this is only true in scenarios where the PDB symbol files can be deployed with the assemblies. Symbol servers are still needed in scenarios where the PDB symbol file is not available (e.g. "attach to process" debugging of a deployment that must exclude symbol files). Unless the PDB files are also deployed (which is not always allowable/possible/etc.), a symbol server would seem necessary.

Additionally, is it really GitLink that makes the symbol servers unneeded, or is it rather the inclusion of the symbol files in the NuGet packages? It would seem that it is the inclusion of the symbol files in the NuGet packages and not GitLink, as this packaging approach is not limited to GitLink and can be used with version control repositories supported by the built-in indexing.

Running for an uncommon / customized URL

Based on testing, there appear to be some problems when file/revision information is provided via the URL query string instead of the URL path. This appears to be a limitation of the Windows Debugging Tools and not GitLink, though this limitation should probably be noted as an aid to other GitLink users.

The URL format with the out-of-the-box GitWeb configuration specifies the file and revision in the URL query string, and the Windows Debugging Tools can't seem to handle this. The GitWeb "read me" notes that this can be changed by enabling PATH_INFO

[GeertvanHorrik]

1. Technically: yes, actually shipping the pdb files makes the symbol servers obsolete. You would still need to ship the (updated) pdb files with your assemblies (via NuGet or your way of deployment). If you are attaching to a process, you could choose to save the updated pdb files somewhere yourself.
2. You are correct, query parameters could be a culprit here. Are you interested in doing a PR for updated documentation?

[mesheets]

I appreciate the follow up.

With deploying PDBs, hasn't deploying them always been an option to avoid symbol server setup? To add some detail to some scenarios alluded to the original post, in some contexts such as security-sensitive or government work, deployment of symbols is forbidden. In other situations, bandwidth/size considerations might preclude deployment of symbols to clients. Perhaps to frame the question another way, is symbol server still needed when the symbols cannot be deployed side-by-side? While pdb files could be saved to a network share, etc., it wouldn't seem to be as convenient as just going ahead and using symbol store, which does the correlation automatically when initiating a debug session?

Related to the build setup with which I've primarily been working, while the source in hosted in an external (non-TFS) Git repository, TFS Team Build is used to generate the builds. I have a command build step that does the GitLink indexing, followed by the out-of-the-box build step to index and publish symbols (albeit with the indexing action disabled, since GitLink is needed in order to properly handle that aspect). I suppose that Team Build build step does make it easier to use symbol server than if building via some other tool without such support provided out-of-the-box.

If my experience with the Windows Debugging Tools in handling query string parameters seems consistent with the experience of others, I can give a look at creating a pull request.

[GeertvanHorrik]

Simply deploying the original pdb's isn't the solution because the paths in the pdb files would point to the paths used on the build server (e.g. C:\CI_WS\12345\MyProject\MyFile.cs), which aren't available on other machines. Replacing the local paths with urls is what GitLink does. If you cannot deploy pdb's, GitLink is not the tool to use.

[mesheets]

OK, that explanation helps, because based on that I don't think we're on the same page, as (1) our setup is working in the exact fashion that seems to be described as not possible and (2) if the symbol files are referencing the build server's local paths, then it would appear that that build process has not been setup/configured correctly. I first started using this type of setup about 10 years ago. Hopefully, perhaps, we can try to clarify.

I'm not sure I follow why non-indexed-mapped symbols would ever be published to Symbol Store? That's the purpose of the Source Indexing mapping step that should precede publishing the symbols. The Source Indexing mapping step "maps" the local paths to not only server-based version control paths but also the exact changeset/commit of the build.

• https://msdn.microsoft.com/en-us/library/windows/desktop/ms680641(v=vs.85).aspx
• https://www.visualstudio.com/docs/build/steps/build/index-sources-publish-symbols

In other words, after the Source Indexing mapping step, the paths in the PDB symbol files are no longer setup to pull "the paths used on the build server (e.g. C:\CI_WS\12345\MyProject\MyFile.cs), which aren't available on other machines."

Actually, users don't even need to have a local copy of the source code or the PDB symbol files, because the debugger will pull down the indexed PDB symbol files from the Symbol Server, and then the indexing+mapping information will tell it not only which file to pull from the server but also which version.

From the MSDN documentation:

Source server currently ships with scripts that should work with the following source-control systems.

• Team Foundation Server
• Perforce
• Visual SourceSafe
• CVS
• Subversion

Obviously, GitLink fills the symbol indexer gap for Git-based version control repositories by making it possible to add Git to the above list of version control systems, but these are all part of Symbol Indexing and not replacements for Symbol Server.

If you cannot deploy pdb's, GitLink is not the tool to use.

I have actually already been able to use GitLink in just such a capacity. I am indeed in situation where PDBs cannot be deployed, but GitLink is indeed able to perform the indexing step prior to publishing to Symbol Server (as alluded to in the Team Build steps described earlier).

At a high level, the basic build sequence is as follows:

• Build source on build server
• Index with GitLink
• Publish to Symbol Server

During debugging, the basic sequence is then as follows:

• The GitLink-indexed PDB symbol files are downloaded from Symbol Server
• Each source file is pulled from the indexed version control path (not the build server's local path) based on the exact commit/changeset against which the assembly was built

Works great, thanks to the combination of both GitLink and Symbol Server! Perhaps there are some areas here where additional documentation and/or how to might be useful?

[GeertvanHorrik]

Interesting approach of the usage of GitLink. I don't have a lot of experience with private symbol source servers myself (only public ones for open-source projects), hence my response that you need to publish the updated pdb files together with the nuget packages making symbol source servers obsolete.

I think you found a nice niche usage of GitLink :-)