RazorEditorParser Class

Definition

Namespace:

Microsoft.AspNetCore.Razor

Assembly:

Microsoft.AspNetCore.Razor.dll

Package:

Microsoft.AspNetCore.Razor v1.1.0

Parser used by editors to avoid reparsing the entire document on each text change.

public ref class RazorEditorParser : IDisposable

public class RazorEditorParser : IDisposable

type RazorEditorParser = class
    interface IDisposable

Public Class RazorEditorParser
Implements IDisposable

Inheritance

Object

RazorEditorParser

Implements

IDisposable

Remarks

This parser is designed to allow editors to avoid having to worry about incremental parsing. The CheckForStructureChanges(TextChange) method can be called with every change made by a user in an editor and the parser will provide a result indicating if it was able to incrementally apply the change.

The general workflow for editors with this parser is:

1. User edits document.
2. Editor builds a TextChange structure describing the edit and providing a reference to the updated text buffer.
3. Editor calls CheckForStructureChanges(TextChange) passing in that change.
4. Parser determines if the change can be simply applied to an existing parse tree node.

NOTE: Additional flags can be applied to the PartialParseResult, see that enum for more details. However, the Accepted or Rejected flags will ALWAYS be present.

A change can only be incrementally parsed if a single, unique, Span (see Microsoft.AspNetCore.Razor.Parser.SyntaxTree) in the syntax tree can be identified as owning the entire change. For example, if a change overlaps with multiple Spans, the change cannot be parsed incrementally and a full reparse is necessary. A Span "owns" a change if the change occurs either a) entirely within it's boundaries or b) it is a pure insertion (see TextChange) at the end of a Span whose EditHandler can accept the change (see CanAcceptChange(Span, TextChange)).

When the RazorEditorParser returns Accepted, it updates CurrentParseTree immediately. However, the editor is expected to update it's own data structures independently. It can use CurrentParseTree to do this, as soon as the editor returns from CheckForStructureChanges(TextChange), but it should (ideally) have logic for doing so without needing the new tree.

When Rejected is returned by CheckForStructureChanges(TextChange), a background parse task has already been started. When that task finishes, the DocumentParseComplete event will be fired containing the new generated code, parse tree and a reference to the original TextChange that caused the reparse, to allow the editor to resolve the new tree against any changes made since calling CheckForStructureChanges(TextChange).

If a call to CheckForStructureChanges(TextChange) occurs while a reparse is already in-progress, the reparse is canceled IMMEDIATELY and Rejected is returned without attempting to reparse. This means that if a consumer calls CheckForStructureChanges(TextChange), which returns Rejected, then calls it again before DocumentParseComplete is fired, it will only receive one DocumentParseComplete event, for the second change.

Constructors

RazorEditorParser(RazorEngineHost, String)

Constructs the editor parser. One instance should be used per active editor. This instance can be shared among reparses, but should never be shared between documents.

Properties

CurrentParseTree

FileName

Host

LastResultProvisional

Methods

CheckForStructureChanges(TextChange)	Determines if a change will cause a structural change to the document and if not, applies it to the existing tree. If a structural change would occur, automatically starts a reparse.
Dispose()	Disposes of this parser. Should be called when the editor window is closed and the document is unloaded.
Dispose(Boolean)
GetAutoCompleteString()

Events

DocumentParseComplete

Event fired when a full reparse of the document completes.