Struct DocumentKey

A SyntaxTree is a transient artifact: the IDE produces a new Compilation holding new trees on every keystroke, so reference identity distinguishes trees only within one compilation and cannot key a cache that outlives it. The permanent identity of a document is therefore needed, and FilePath is the only candidate reachable where it is needed: a Roslyn analyzer callback carries a SemanticModel and nothing else, the cross-process contract passes a path, and WorkspaceProvider returns no workspace at all in a supported host, so no DocumentId is available. See issue #1742.

This type exists because a bare string made two mistakes easy. It let the comparer be chosen per dictionary, which is how the design-time indexes came to compare paths ordinally while the command-line compiler deduplicates them with OrdinalIgnoreCase. And it let one key space be confused with another, because a document path, an introduced syntax tree name and a source generator hint name are all strings; the duplicate-introduction assertion of DesignTimeAspectPipelineResult was exactly such a confusion. Keeping document paths in a distinct type makes both a compile error.

The comparison is ordinal. Case-insensitive comparison would match the command-line compiler on Windows and be wrong on Linux, where two paths differing in case are two files.

The hash code is computed once, on construction. These keys are long strings compared and hashed on every lookup of the design-time hot path, so caching the hash is why this type is not slower than the string it replaces.

A key is a value, not a reference into a compilation. It does not guarantee that the document exists in any given compilation, and it deliberately does not carry the SyntaxTree: a cache entry that held one would root the syntax tree of an earlier compilation.