Expose the semantic model to the XPath queries of MA0240
What
The MA0240 banned syntax queries can now read the semantic model through a semantic XML namespace:
//AddExpression/*[@semantic:TypeConstructedFrom='System.Nullable`1']; Do not add nullable values
//MethodDeclaration[@semantic:ReturnTypeConstructedFrom='System.Threading.Tasks.Task`1']; Return a ValueTask instead
//InvocationExpression[@semantic:SymbolDocumentationId='M:System.Console.WriteLine(System.String)']; Use the logger
Why
The queries were purely syntactic, so banning "an addition on a Nullable<T>" or "a call to Console.WriteLine" required writing a dedicated analyzer. A separate namespace keeps these attributes from clashing with the token attributes, which are named after the properties of the syntax nodes.
The attributes
16 attributes on every element: Type, TypeConstructedFrom, TypeConstructedFromDocumentationId, the three ConvertedType* equivalents, the three ReturnType* equivalents, Symbol, SymbolDocumentationId, SymbolKind, ContainingType, ContainingTypeDocumentationId, HasConstantValue and ConstantValue.
An attribute is absent when there is no value for it, so !=, not(), starts-with() and count() all behave as expected. The names come in three formats, built by the new SymbolNameFormatter since ToDisplayString cannot emit the arity suffix:
- display name with the type arguments,
System.Nullable<System.Int32> - metadata name, as
GetTypeByMetadataNameexpects it,System.Nullable`1 - documentation comment id,
T:System.Nullable`1
Notes for the reviewer
- Cost. The rule only registers a
SemanticModelActionwhen a query actually uses the prefix; otherwise it keeps theSyntaxTreeActionit had. In a file that mixes both, the syntactic entries are evaluated on a navigator built without a semantic model, so they do not pay for the semantic attributes. - Typos. MA0241 now reports
'Typo' is not a valid semantic attributeand undefined namespace prefixes, so a typo cannot silently disable a ban. The scanner skips XPath string literals. CreateDeclarationIdvs the XML documentation file.CreateDeclarationIdappends the return type of every method that does not returnvoid, whereas the compiler only does it for the conversion operators. The emitted id is the documentation one, so it can be copied from a.xmldocumentation file or aBannedSymbols.txt:M:System.String.Substring(System.Int32), andM:Sample.op_Implicit(Sample)~System.Int32keeps its suffix.- Roslyn 4.8.
CreateDeclarationIdthrows for the symbols that cannot be documented (a parameter, an alias, an array type, a type parameter), where the more recent versions returnnull.GetDocumentationIdallow-lists the symbol kinds, so a local, a parameter, an alias, a lambda and a local function simply have nosemantic:SymbolDocumentationId. - XPath mechanics were verified before being relied on: namespaced attributes match on a custom
XPathNavigatorbystring.EqualsonLocalName/NamespaceURIwith noNameTableatomization, an undefined prefix throws at compile time (so it already flows into MA0241 through the existingcatch), and the resolver is snapshotted into the compiled expression, so it survives theClone()the staticQueryCacherelies on. GetTypeInfo/GetSymbolInfo/GetConstantValue/GetDeclaredSymbolnever throw for an arbitrarySyntaxNode; the only preconditions are non-null and same-tree, both guaranteed by the navigator. A test runs asemantic:query over a file exercising ~117 node kinds to prove it.
Tests
28 tests added to DoNotUseBannedSyntaxAnalyzerTests, one per attribute plus the declared-symbol fallback, the reported name and span of a semantic attribute, a file mixing syntactic and semantic entries, the node-kind robustness sweep, and the MA0241 cases.
The full suite passes on all five Roslyn versions (23,980 tests). dotnet run --project src/DocumentationGenerator reports no change.