The page compiler

All assemblies · uk.osric.asp.Runtime · 15 types · 54 entries

uk.osric.asp.Runtime

AccessibleTableRenderer

Renders a Markdown table as HTML the site can serve.
Markdig's own table renderer writes column alignment as an inline style attribute and writes header cells without a scope. The site's CSP is style-src 'self' with no 'unsafe-inline', and its accessibility rules require a scope on every header cell, so both profiles use this renderer instead: alignment is ignored and every header cell is a column header.

CompileResult

The outcome of compiling generated page source.

MethodCompileResult(byte[] Image, byte[] Symbols, IReadOnlyList<PageDiagnostic> Diagnostics)

The outcome of compiling generated page source.

Parameters

Image
The emitted assembly, or null when compilation failed.
Symbols
The emitted portable PDB, or null when compilation failed.
Diagnostics
The author-facing diagnostics, errors and warnings, in template space. Empty when the page compiled cleanly. Compilation.PageDiagnostic values rather than Roslyn types keep Roslyn out of the shell.

PropertyImage

The emitted assembly, or null when compilation failed.

PropertySymbols

The emitted portable PDB, or null when compilation failed.

PropertyDiagnostics

The author-facing diagnostics, errors and warnings, in template space. Empty when the page compiled cleanly. Compilation.PageDiagnostic values rather than Roslyn types keep Roslyn out of the shell.

PropertyIsSuccess

Whether the page can run; warnings do not stop it.

PropertyLibraries

The keys of the libraries the page was compiled with, in ordinal order; empty when it named none. An image that carries this list was built against exactly these libraries.

PropertyKind

What the compiler judged a declaration-only source to be, or null when it refined nothing. Generation can tell a template has only declarations; whether those declarations are a Worker is a question only the compiled types answer.

DiffRenderer

The host's diff renderer: the page and editor table and the assistant's unified text.

ToHtml is the page capability and the editor's view. It escapes every source line, so the result is safe for any string, and writes no inline style: the table, the hunk row, the change markers and the sideways scroll container are all classes the site's sheets style.

ToUnifiedDiff is the assistant's form, beside the table the way ToRestrictedHtml sits beside the page profile. It is not on the Sdk capability, because a page does not need text; a page that does can render the changes itself.

The renderer is stateless. The diff itself is pure and bounded by Diff.LineDiff.

MethodToHtml(string, string)

Renders a line diff of two documents as HTML.

Inherited from IDiffRenderer.ToHtml.

Parameters

before
The earlier document.
after
The later document.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
Either document is null.

MethodCompare(string before, string after)

Compares two documents with the renderer's own engine.

Parameters

before
The earlier document.
after
The later document.

Returns

The line changes, which ToHtml and ToUnifiedDiff consume.

Exceptions

ArgumentNullException
Either document is null.

MethodToUnifiedDiff(string before, string after)

Writes the comparison as unified diff text, for a tool result.

Parameters

before
The earlier document.
after
The later document.

Returns

The text ToUnified writes; empty when nothing changed.

Exceptions

ArgumentNullException
Either document is null.

IPageCompiler

Compiles generated page source into an assembly image and loads compiled pages.
The shell depends on this interface rather than on a compiler type, so compilation can be counted, timed or replaced without the shell naming Roslyn.

PropertyRuntimeId

Identifies the build that produced a compiled image.
Images carrying a different value were produced by a build with a different page contract, or under a different page API policy, and must be compiled again before they are run.

MethodCompile(GeneratedSource source, IReadOnlyList<LibrarySource> libraries, CancellationToken cancellationToken)

Compiles generated C# source into an assembly image.

Parameters

source
The generated page source, not the page template.
libraries
Every library the page could name, or an empty list when it names none. The compiler keeps the ones the page's using directives reach, and their own, and compiles them into the page's assembly.
cancellationToken
Bounds the compile. Roslyn observes it between operations rather than inside one, so it is a coarse bound on a pathological template, not a hard one.

Returns

The image and the author-facing diagnostics when the page does not compile, and the keys of the libraries it used, so a caller can record what the image depends on without deriving it again.

Exceptions

InvalidOperationException
The generated source itself is broken. A fault is not a page diagnostic and must reach the shell as an exception.

MethodCompileWorker(GeneratedSource source, IReadOnlyList<LibrarySource> libraries, CancellationToken cancellationToken)

Compiles a declaration-only source: a library is checked, a worker is emitted.

Parameters

source
The declarations the template contributes, generated by GenerateLibrary rather than as a page.
libraries
Every library the source could name, or an empty list when it names none.
cancellationToken
Bounds the analysis. Roslyn observes it between operations rather than inside one.

Returns

The author-facing diagnostics, the kind the compiler refined the source to (Kind), and an image only when it declares a worker: a library's answer is its errors, because what it contributes to a dependent is compiled into that page.

Exceptions

InvalidOperationException
The generated source itself is broken. A fault is not an author diagnostic and must reach the shell as an exception.

MethodLoad(byte[] image, byte[] symbols)

Loads a compiled image and its portable symbols so its handler can be run.

Parameters

image
The bytes an earlier Compile emitted.
symbols
The portable PDB bytes emitted with the image, if present.

Returns

The loaded handler; dispose it to release the assembly.

MethodLoadWorker(byte[] image, byte[] symbols)

Loads a worker image and finds the one entry point it declares.

Parameters

image
The bytes an earlier CompileWorker emitted.
symbols
The portable PDB bytes emitted with the image, if present.

Returns

The loaded worker; dispose it to release the assembly.

Exceptions

InvalidOperationException
The image does not declare exactly one worker entry point, so there is nothing to run.

JavaScriptValidator

Parses JavaScript as an ECMAScript module and reports its syntax errors in page positions.
Syntax only: the grammar is checked and nothing is executed, imported or resolved. A page is parsed as a module because that is the site's convention for a script page, so a top-level return is an error and a duplicated top-level declaration is a redeclaration.

MethodValidate(string script)

Parses a script as an ECMAScript module and returns positioned syntax diagnostics.

Parameters

script
The JavaScript to parse.

Returns

The parser's error, if any, and up to twenty unclosed-opener hints, ordered for display. Empty when the script parses.

Exceptions

ArgumentNullException
script is null.

LibrarySource

One library a page may name: the key it is stored under and the unit it contributes.

MethodLibrarySource(string Key, GeneratedSource Source)

One library a page may name: the key it is stored under and the unit it contributes.

Parameters

Key
The library's canonical key, which is how a diagnostic names it.
Source
The declarations the library contributes, generated by GenerateLibrary rather than as a page.

PropertyKey

The library's canonical key, which is how a diagnostic names it.

PropertySource

The declarations the library contributes, generated by GenerateLibrary rather than as a page.

LoadedPage

A compiled page, loaded into its own collectible assembly load context.
One instance is cheap to create from stored bytes and safe to invoke repeatedly; each invocation still gets a fresh handler instance so page fields cannot leak between requests.

Nothing here suppresses inlining: MethodInfo.Invoke throws its wrapper whether or not the caller was inlined, and ExceptionDispatchInfo restores the original stack. If unloading a collectible context ever appears to hang, inlining is the knob to revisit.

MethodInvokeAsync(IContext context)

Runs the page against a request context.

Parameters

context
The context the page writes to.

Returns

A task that completes when the page has finished.

Exceptions

Exception
Whatever the page threw, unwrapped.

MethodDispose()

Marks the load context for unloading.

LoadedWorker

A compiled worker, loaded into its own collectible assembly load context.
The image was checked when it was saved, so a missing or doubled entry point here is a stored image that no longer matches the running build rather than an author's mistake; it is still an exception, because there is nothing sensible to run.

MethodLoadedWorker(byte[] image, byte[] symbols)

Loads a worker image and finds the one entry point it declares.

Parameters

image
The bytes an earlier CompileWorker emitted.
symbols
The portable PDB bytes emitted with the image, if present.

Exceptions

InvalidOperationException
The assembly does not declare exactly one worker entry point.

MethodCreate()

Creates an instance of the worker's entry point.

Returns

A fresh worker, so nothing a finished job left behind reaches the next one.

MethodDispose()

Marks the load context for unloading.

MarkdownRenderer

The host's Markdown renderer: one author-facing profile and one restricted profile.

The page profile is CommonMark with heading anchors, pipe tables and auto-links, and raw HTML passes through: IMarkdownRenderer says what that means for a page author (`pages-markdown`). A page switches those three features per call with MarkdownOptions.

The restricted profile is for model output. Raw HTML is rendered as text, there are no autolinks or images, links pass Markdown.LinkPolicy, and every heading is written as h3 so a model-chosen level cannot skip one in the transcript. Both profiles use the site's table renderer, which writes scope="col" and no inline style (`pages-markdown`).

The parser pipelines are built once per option set and are safe to share. Markdig's HtmlRenderer is stateful, so one is created for each call.

MethodToHtml(string)

Renders a Markdown document to HTML with the page profile.

Inherited from IMarkdownRenderer.ToHtml.

Parameters

markdown
The Markdown to render. Raw HTML in it is passed through.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
markdown is null.

MethodToHtml(string, MarkdownOptions)

Renders a Markdown document to HTML with the features the page chooses.

Inherited from IMarkdownRenderer.ToHtml.

Parameters

markdown
The Markdown to render. Raw HTML in it is passed through.
options
The features to switch on or off for this render.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
markdown or options is null.

MethodToRestrictedHtml(string markdown)

Renders model output as the restricted subset the assistant transcript shows.

Parameters

markdown
The Markdown to render.

Returns

HTML that is safe to write into the assistant transcript.

Exceptions

ArgumentNullException
markdown is null.

PageApiChecker

Checks generated page source against Compilation.PageApiPolicy before it is emitted.
Roslyn lives here so Core does not have to: the walk turns symbols into plain Compilation.ApiReference values and the policy decides. The shape rule is separate from the API list because it is about the generated source as a whole rather than any one symbol.

MethodCheck(SyntaxTree tree, SemanticModel model, IReadOnlyCollection<SyntaxTree> authored)

Reports everything the page may not do.

Parameters

tree
The parsed generated source.
model
The semantic model bound to tree.
authored
Every tree the page may call as its own code — itself and the libraries it pulled in — or null when it named none. Each one is checked in its own right; this is only what stops a page's own declared types looking foreign.

Returns

The author-facing diagnostics to fail the compile with; empty when the page is acceptable.

Exceptions

InvalidOperationException
The generated source itself violates the policy. That is a compiler fault, not a page error.

MethodCheckLibrary(SyntaxTree tree, SemanticModel model, IReadOnlyCollection<SyntaxTree> authored)

Reports everything a library may not do.

Parameters

tree
The parsed generated library source.
model
The semantic model bound to tree.
authored
The trees whose own types the policy trusts; the library and its closure when omitted.

Returns

The author-facing diagnostics to fail the compile with; empty when the library is acceptable.

Exceptions

InvalidOperationException
The generated source itself violates the policy. That is a compiler fault, not an author's error.

PageCompiler

Compiles generated page source into page images and loads them for execution.

MethodPageCompiler()

Creates a compiler for this process's runtime.

Exceptions

InvalidOperationException
The runtime does not describe its platform assemblies, so no page could be compiled.

PropertyRuntimeId

The SDK's module version id covers what a page binds against; Core's covers the generator, so a change that alters the generated source invalidates an image even when the contract is unchanged.

MethodCompile(GeneratedSource source, IReadOnlyList<LibrarySource> libraries, CancellationToken cancellationToken)

Compiles generated C# source into an assembly image.

Parameters

source
The generated C# source, not the page template.
libraries
The compiled sources the page named, in closure order.
cancellationToken
Bounds the compile between Roslyn operations.

Returns

The image, and the author-facing diagnostics when the page does not compile.

Exceptions

InvalidOperationException
The generated source itself is broken. A diagnostic without a template position means the fault is in code the generator wrote, not in the page, so it must not be shown to the author.

MethodCompileWorker(GeneratedSource, IReadOnlyList<LibrarySource>, CancellationToken)

A declaration-only source is analysed first: a worker is emitted, so the runner has something to load, while a library is not, because there is nothing to run and the one thing an author needs is the diagnostics.

MethodLoad(byte[] image, byte[] symbols)

Loads a compiled image so its handler can be run.

Parameters

image
The bytes an earlier Compile emitted.
symbols
The portable PDB emitted beside the image, when there was one.

Returns

The loaded handler; dispose it to release the assembly.

MethodLoadWorker(byte[] image, byte[] symbols)

Loads a compiled worker so its entry point can be run.

Parameters

image
The bytes an earlier CompileWorker emitted.
symbols
The portable PDB emitted beside the image, when there was one.

Returns

The loaded worker; dispose it to release the assembly.

PageLoadContext

The load context every compiled page gets.

A page may use the SDK and the base class library, but not the site: naming one of the shell's own assemblies resolves here, and this context refuses it instead of falling back to the default one. Throwing rather than returning null is the point - null means "ask the default context", which is how a page could otherwise reach uk.osric.asp.Web by name.

uk.osric.asp.Sdk is deliberately not denied: it is the page contract, and the fallback to the default context hands the page the same copy of IContext the host is using, so the handler signature matches.

uk.osric.asp.Core is host support — the template pipeline, diagnostics and charts — and is denied like the rest of the site. A page names the SDK and the base class library, nothing else.

This is isolation from the app's internals, not a sandbox. A page still runs with the site's identity and can use the base class library; only the shell and the web stack are out of reach.

MethodPageLoadContext()

The load context every compiled page gets.

A page may use the SDK and the base class library, but not the site: naming one of the shell's own assemblies resolves here, and this context refuses it instead of falling back to the default one. Throwing rather than returning null is the point - null means "ask the default context", which is how a page could otherwise reach uk.osric.asp.Web by name.

uk.osric.asp.Sdk is deliberately not denied: it is the page contract, and the fallback to the default context hands the page the same copy of IContext the host is using, so the handler signature matches.

uk.osric.asp.Core is host support — the template pipeline, diagnostics and charts — and is denied like the rest of the site. A page names the SDK and the base class library, nothing else.

This is isolation from the app's internals, not a sandbox. A page still runs with the site's identity and can use the base class library; only the shell and the web stack are out of reach.

MethodLoad(AssemblyName)

Exceptions

NotSupportedException
The page tried to load an assembly it may not use.

PageReferenceSet

The assemblies a page is compiled against.
Built once per process, because re-reading and re-creating the platform references is the expensive part of compiling a small page. A runtime that cannot supply the set has no working reference set at all, so it fails here rather than in the first page that is compiled.

MethodForPages()

The reference set the runtime provides, trimmed to what a page may name.

Returns

The references to compile generated page source against.

Exceptions

InvalidOperationException
The runtime did not describe its platform assemblies, or described none that pages can use.

MethodReferencedPaths(string trustedPlatformAssemblies)

The platform assembly paths a page may reference.

Parameters

trustedPlatformAssemblies
The runtime's TRUSTED_PLATFORM_ASSEMBLIES value, as read from AppContext.GetData.

Returns

The paths that remain, in the order the runtime listed them.

Exceptions

InvalidOperationException
The value is missing, empty, or names no assembly every page is built on.

RestrictedHeadingRenderer

Writes every Markdown heading as the transcript's one heading level.
The transcript already has an h2 naming the speaker, and a model chooses its own heading depth without seeing the document it lands in. Flattening to h3 means no heading can skip a level, at the cost of the model's own hierarchy, which the text can say anyway.

RestrictedLinkRenderer

Renders a link only when Markdown.LinkPolicy allows its URL.
An image is never an img: its alt text is written instead, so a Markdown image cannot load a remote resource. A refused link keeps its text and loses its anchor, which makes a hostile URL visible as the words the model wrote rather than a place to click.