ReferenceBuilt-in steps
hover-csharp
The hover-csharp step: hovers and errors of C# fences with the Roslyn language server.
uses: hover-csharp checks the C# code fences of HTML pages with the Roslyn language server and stores on each the
hovers of its symbols (signature and documentation) and its errors, in the shape of the
hover-typescript step's results, so that the same renderer
(highlight) shows them.
| Shape | reduce (no group-by) |
Default match |
**/*.html |
| Default workflow | no |
What it doesLink to this heading
Every fence of an HTML page that the markdown step wrote with a language of languages (csharp, cs, c#),
and, when trigger is set, whose meta has that word, gets a data-twoslash attribute with twoslash's shape:
{ "code": ..., "nodes": [...] }, the hovers and the errors. The fence itself is unchanged, and the step sets no
metadata.
Snippets compile in generated projects. A snippet can be top-level statements, type declarations or class members:
each is wrapped in a namespace of its own, so that the snippets of a project do not see each other. A fence uses the
project of its meta's project=name, else the first project whose titles end its title, else the first whose
patterns match its code, else default (an empty project when projects does not declare it).
A snippet with errors fails the build, naming its page, the fence's number on the page and its first line
(/docs/a.md: csharp fence 1 ('var x = ...'): ...); with errors: warn it is a warning, and the fence renders its
errors. ignore lists diagnostic codes that are neither reported nor rendered.
OptionsLink to this heading
| Option | Type | Default | Meaning |
|---|---|---|---|
projects |
mapping of names to projects | default, an empty project |
the generated projects, see below |
trigger |
string | none | a word the meta of a fence must have to be checked; every fence of languages when not set |
ignore |
string or list | none | diagnostic codes neither reported nor rendered (CS8321) |
version |
string | 5.13.0-1.26514.10 |
the version of the language server to download (roslyn-language-server.<rid>) |
path |
string | none | the language server's Microsoft.CodeAnalysis.LanguageServer.dll, relative to the source folder, instead of downloading it |
registry |
string | https://api.nuget.org/v3-flatcontainer/ |
the NuGet package content url (an http or https url) the server is downloaded from |
dotnet |
string | DOTNET_HOST_PATH, else dotnet on the PATH |
the dotnet of the .NET SDK that restores the projects and runs the server, relative to the source folder |
languages |
string or list | [csharp, cs, "c#"] |
the fence languages the step checks |
errors |
string | fail |
fail: a snippet with errors fails the build; warn: it is a warning |
tab-width |
integer, 0 to 16 | 0 |
replace tabs with that many spaces first; 0 keeps them |
trim |
boolean | true |
remove the spaces at the end of lines and the blank lines around the code first |
processes |
integer, 1 or more | the processor count, at most 4 |
language servers at once |
timeout |
integer, 1 or more | 300 |
seconds each language server has |
Each project of projects:
| Field | Type | Default | Meaning |
|---|---|---|---|
sdk |
string | Microsoft.NET.Sdk |
the project SDK (Microsoft.NET.Sdk.Web) |
framework |
string | net10.0 |
the target framework |
packages |
mapping of ids to versions | none | package references (Some.Package: "1.2.3") |
usings |
list | none | global usings, over the SDK's implicit ones |
properties |
mapping of names to values | none | MSBuild properties |
files |
mapping of paths to paths | none | shared files of the source folder (stubs that snippets use): a relative path in the project, without . or .., to a file of the source folder |
context |
string | none | a class, of a shared file, that statements run in: its fields are the variables that fragments use without declaring them |
titles |
list | none | fence titles, or their ends (Program.cs), that select the project |
patterns |
list | none | regular expressions, one of which the code of a fence must match to select the project when no title matched |
RequirementsLink to this heading
- The .NET SDK, 10 or later (
dotnet, orDOTNET_HOST_PATH, or thePATH's), which also restores the projects. - The Roslyn language server. Without
path, it is downloaded on first use from nuget.org (registry), the package of the current platform, into<cache>/tools/roslyn/<version>/<rid>/.douze tools installdownloads it ahead.
douze doctor checks both. A build that has no snippet to check starts no language server.
CachingLink to this heading
Each fence's outcome, errors included, is kept in the cache by its language, its code, its project and what the step
depends on: the language server and its version (or the content of the path file), the projects (their fields and
the content of their files), ignore, tab-width and trim. A build checks only new snippets.
The step is a reduce: it waits for every page it consumes before it checks them.
ErrorsLink to this heading
douze.yml(6,3): error: project 'web' of step 'cs' has an unknown field 'packges'; did you mean 'packages'?
douze.yml(6,3): error: option 'projects' of step 'cs' must be a mapping of project names to projects
douze.yml(6,3): error: field 'usings' of project 'web' of step 'cs' must be a list of strings
douze.yml(6,3): error: pattern '(' of project 'web' of step 'cs' is not a regular expression: ...
douze.yml(6,3): error: option 'registry' of step 'cs' must be an http or https url
ExampleLink to this heading
site:
content: docs
steps:
pages:
inputs: "docs/**"
uses: frontmatter
permalink:
needs: pages
uses: permalink
with:
root: docs
markdown:
needs: permalink
uses: markdown
csharp:
needs: markdown
uses: hover-csharp
with:
errors: warn
projects:
web:
sdk: Microsoft.NET.Sdk.Web
titles: [Program.cs]
packages:
Some.Package: "1.2.3"
usings: [Some.Namespace]
highlight:
needs: csharp
uses: highlight
write:
needs: highlight
uses: write