Letters from the (VS) Editor

Moving on

Noah Richards — Tue, 08 Feb 2011 04:42:00 GMT

It's been an interesting journey, these last 3 ½ years. I was hired at Microsoft, after an internship the summer before my senior year, to work on a long-lead effort creating new IDE components and developer tools. On my first day back, my boss from the internship sat me down and broke the news that that project I'd come back to work on had been canceled. Instead, I was told we'd be putting the editor from that project into Visual Studio, which would require a fairly small shim layer to get things working. Since then, I’ve had 3 leads (Tim, Fiona, and Michael), moved offices only once (!), written a lot of shims, released 14 extensions to the VS gallery with ~130,000 (non-unique) downloads, worked with a lot of other VS teams to make the editor not crash too much, helped Blend/Powershell/DynamicsAX host the editor outside of VS, wrote box selection, contributed to a number of other VS2010 editor features, fixed about 400 bugs, and collected only one “official” demerit.

I feel that it's time for something new, so I've decided to pursue career opportunities outside Microsoft. My last day here is February 18th, after which I'll be starting a new job in Kirkland.

I'm not sure what will happen to this blog. If the articles are taken down, you can the source (in markdown) for most of them on my github blog project. You can also continue to find me on twitter (@noahsmark), and email me (I'm noah, the domain is noahsmark.com).

I'm not sure who all reads this blog, but I want to say thanks to you anyways. One of my favorite parts of working on the editor has been working with people writing extensions for Visual Studio, so thanks for all the questions and feedback.

Code Snippet: Ensuring a file is in a project

Noah Richards — Fri, 28 Jan 2011 18:16:00 GMT

Every couple of weeks, I'll get a question about getting an arbitrary file on disk into a project in VS without asking VS to open in a document window directly. It seems to be pretty hard to find information for (when I needed to do it, it took a few email threads with various other teams to figure it out), so here's a code snippet I use for this. It works by adding the file to the miscellaneous files project (if it isn't already in another project) and then returning the hierarchy/itemid for the file, which can be used with other methods involving the shell, opening documents, locking documents, etc.

///
<summary>

///
If the given file isn't in a project, put it in the miscellaneous files project, and return

///
the project/itemid of the file.

///
</summary>

///
<returns>hresult (failure code)</returns>

static int
EnsureFileInAProject(string
fileName,
out
IVsUIHierarchy hierarchy, out uint itemId)

{

    IVsUIShellOpenDocument shellOpenDocument = ServiceProvider.GlobalProvider.GetService(typeof(SVsUIShellOpenDocument))
as
IVsUIShellOpenDocument;

    IOleServiceProvider unused;

int
pDocInAProject;

// Before we can take a lock, we need to make sure the given doc data is in a project.
 
// First, ask the shell if it already is

if
(ErrorHandler.Failed(shellOpenDocument.IsDocumentInAProject(fileName,
out
hierarchy,
out
itemId,
out
unused,
out
pDocInAProject)))

    {

        Debug.Fail("IsDocumentInAProject failed, which is unexpected.");

return
VSConstants.E_FAIL;

    }

// We need to add it to the miscellaneous files project if it isn't in a project.

if
(pDocInAProject == (int)__VSDOCINPROJECT.DOCINPROJ_DocNotInProject)

    {

var
externalFilesManager = Shell.Package.GetGlobalService(typeof(SVsExternalFilesManager))
as
IVsExternalFilesManager;

if
(externalFilesManager == null)

        {

            Debug.Fail("Can't find the miscellaneous files project to use.");

return
VSConstants.E_FAIL;

        }

// Make sure the misc files project doesn't actually *open* the document

uint
createFlags = (uint)__VSCREATEDOCWIN.CDW_RDTFLAGS_MASK | (uint)_VSRDTFLAGS.RDT_PlaceHolderDoc;

Guid
emptyGuid = Guid.Empty;

int
unusedPos;

        IVsWindowFrame unusedFrame;

if
(ErrorHandler.Failed(externalFilesManager.AddDocument(createFlags, fileName, IntPtr.Zero,
IntPtr.Zero,
ref
emptyGuid,
null, ref emptyGuid,
null, null, out unusedPos,
out
unusedFrame)))

        {

            Debug.Fail("Couldn't add the document to miscellaneous files project.");

return
VSConstants.E_FAIL;

        }

        IVsProject miscProject;

if
(ErrorHandler.Failed(externalFilesManager.GetExternalFilesProject(out
miscProject)) ||

            (hierarchy = miscProject as IVsUIHierarchy) ==
null
||

            ErrorHandler.Failed(hierarchy.ParseCanonicalName(fileName,
out
itemId)))

        {

            Debug.Fail("Couldn't get the misc files project or item we just added.");

return
VSConstants.E_FAIL;

        }

     }

return
VSConstants.S_OK;

}

Editor fundamentals: Text-Relative Adornments

Noah Richards — Wed, 25 Aug 2010 17:30:00 GMT

Tagging along with the last editor fundamentals post on the pull/event model, today's article is the application of that model to handling text-relative adornments.

The adornment "manager"

Within the editor, we use a fairly common pattern for structuring adornments. There are essentially two components:

First, a view creation listener (IWpfTextViewCreationListener), keyed off a ContentType and TextViewRole. Most general adornment providers use "text" and PredefinedTextViewRoles.Interactive. It's also handy to put your AdornmentLayerDefinition here, keeping all your MEF components in one place.

Second, you have an adornment manager, for which there is no interface to implement or base class to inherit. This will be your controller (in the Model-View-Controller sense), that controls adds adornments to the adornment layer when necessary. It's created by the view creation listener above.

Adding adornments to the layer

The obvious way to deal with adornments is, unfortunately, not the simplest or best performing. To understand how to handle this best, you have to step back from adornment API specifically and consider how the view works in general.

Much like a text buffer is some data (text, in the form of CurrentSnapshot) and an event for when that data changes, a view is some data (specific to a certain ITextSnapshot) and an event for when that data changes (LayoutChanged). There are other events in there, for when the viewport size changes or when horizontal scrolling happens, but we'll ignore those for now.

Though it is easiest to imagine the view as an extremely tall list of lines inside a scrollable viewport, that effect is faked. The view is only really the lines that are currently visible, which it transposes when scrolling and redraws when the buffer changes.

Likewise, it is best to think about adornment layers in the same way. Though you have an essentially infinite canvas, the adornment layer should only contain adornments that are either viewport-relative (e.g. an adornment that always shows up in the top-right corner of the editor, regardless of what text is visible) or text relative (e.g. the red breakpoint marker under pieces of text). The former can essentially ignore layout completely, but the latter is intimately tied to layout.

So, the obvious way to handle adornment layers is to figure out where all the adornments should go, regardless of where they appear in the file, and push them all onto the adornment layer. The API is generally suggestive of this, as the adornment layer has Add/Remove events like any other collection. However, there are two issues with using the API in this way: performance and, well, difficulty in making it work.

For performance, the issue is the same reason why the view doesn't render every line in the file all the time. If it did so, resources would be dedicated relative to the size of the file, meaning you'd have difficulty scaling as file size increased. If you only need to scale to the viewport height, though, you'd have a reasonable upper bound (barring zooming out). In the abstract, also, you'd know that you are only doing exactly as much work as you need, since the only purpose of adornments is for the user to see them, and the user can only see what's currently visible in the buffer. Besides that, you can't actually determine the correct y-coordinate of a line outside of the visible region, because the view doesn't compute it (to do so, it would have to render every line in-between to add up their heights).

For correctness, you need to consider how text-relative adornments work. Though you aren't required to add them in response to a layout, they will be removed for you if they (1) have a VisualSpan (an associated span of text) and (2) any part of that text is reformatted in the view, either because it was scrolled into view or because the underlying text was changed. As such, you can't just throw these text-relative adornments into the view and assume they won't disappear at some point. You have to listen for LayoutChanged anyway, so you may as well use that as the primary mechanism for adding adornments to the view.

Data sources

Virtually all of the built-in adornment managers work by consuming tags, via an [Import]ed IViewTagAggregatorFactoryService. This carries the normal benefits of tagging and fits into the same pattern as:

LayoutChanged → Draw adornments per line

If use use a pattern like this for the tagging aspect, you'll get to share most of the complex parts of the code path (in draw per line):

TagsChanged → Get intersecting lines → Clear adornments on the line → Draw adornments per line

When you structure it like this, your adornment manager truly is just a controller. It acts as a pass-through for data coming from the tagger and finding an eventual home as an adornment in the adornment layer, but it doesn't store this information locally.

Layout + tagging

Here's roughly what your LayoutChanged handler will look like:

for each line in e.NewOrReformattedLines
    for each tag in tagAggregator.GetTags(line.ExtentAsMappingSpan)
        create an adornment for the tag
        add that adornment to the visual layer

(Where either the inner loop or the body of the inner loop are best placed in a helper method, so they can be called on TagsChanged as well)

The logic is fairly simple, and your manager is now acting more like a translator from a tag type to a visual. Because you only respond to layout, you don't need to worry about adding unnecessary adornments for lines that aren't visible, and you don't need to worry about tracking buffer changes to update when text changes.

Your TagsChanged handler will be similar:

for each tagSpan in e.Span.GetSpans(view.Textsnapshot)
    for each line in view.TextViewLines.GetTextViewLinesIntersectingSpan(tagSpan)
        remove adornments on that line
        add new adornments on that line

If you want to combine these two, you'd probably want to extract out a method for DrawAdornmentsOnLine or DrawAdornments(NormalizedSnapshotSpanCollection). At the very least, the code for creating an adornment from a tag and/or adding an adornment to the layer should be in a shared method.

One last caveat: this pattern works best when your adornments don't span multiple lines. Using these methods, if an adornment spans multiple lines, you can end up removing/adding adornments more than once, depending on how the tag spans are placed. If your adornments are mostly on single lines, it isn't something necessarily worth worrying about as there won't be other ill-effects of this method (you won't double-draw or skip drawing adornments). If you do either know you have lots of multi-line adornments or have profiled it to see it's a performance issue, you'll want to do something a bit smarter about collecting lines into normalized spans and querying tags over those spans. You could do that for the simple case anyway, but it's a little more complicated than is conducive for a blog post.

Other considerations

An interesting consideration is how an adornment manager should behave around outlining. The good news is that it is easy if you use tagging and operate over lines at a time instead of using spans, e.g. use the NewOrReformattedLines property on the TextViewLayoutChangedEventArgs, instead of NewOrReformattedSpans. Just use the ExtentAsMappingSpan property on the line instead of using the regular Extent, as the example above shows. The line's mapping span skips collapsed outlining regions, as well as any other type of adornment that is eliding text (there aren't others in the product, though extensions can provide their own).

(This is also the reason why, if you go the normalization route that I mentioned just a second ago, you still want to walk and normalize the information on a line-by-line basis, rather than using the pre-normalized NewOrReformattedSpans. If you do want to go this route, convert the mapping spans to snapshot spans on the ITextView.TextSnapshot, put them all in a list/enumeration of SnapshotSpan, combine the result in a NormalizedSnapshotSpanCollection, and iterate over that when calling GetTags. Clear as mud, I know, but it gets to be somewhat second nature once you've written a couple of these. Just remember that the Normalized(Snapshot)SpanCollection classes, methods, and static methods are a huge helper when working with collections of (Snapshot)Spans).

On the other hand, if you do want to display adornments for text that is hidden, just switch back to Extent. How you visualize that information will take some consideration, especially if your adornment really is underneath the text and not just an annotation in the vicinity of the text.

Spell Checker Update - Perf bug on large C# files

Noah Richards — Thu, 12 Aug 2010 17:15:00 GMT

I pushed an update (v2.22) to the Spell Checker extension just a little bit ago which fixes a pretty major and annoying performance issue with large C# files. I say "fixes", but it's really just a big work around, courtesy Michael (who will post an entry on his blog any day now. It's interesting enough that I thought I'd share a little bit of information about performance, as it applies to this extension.

For reference, if you haven't seen it, the bug manifests itself by pegging your CPU if you open a C# file of, say, over 1000 lines. It isn't a hard value like that, being a function of how many multi-line statements (comments, strings, etc.) you have in the file, but I've yet to hit it on a file smaller than 1000 lines.

First, a little digression to talk about how the extension works:

Somewhat greedy spell checking

The spell checker's overall loop is fairly simple:

When a file is opened, scan the entire buffer for spelling mistakes. This puts the entire buffer into a known state.
When text is changed, mark lines that contain those changes as dirty.
After about 500ms of idle time (e.g. not during fast typing), scan the dirty lines again for spelling mistakes.

The one big design decision made here is that the spell checker is greedy; it doesn't just spell check what is visible, which would have actually escaped the bug that caused this performance issue on large C# files, as long as you weren't zoomed out or didn't have a really tall monitor. However, doing it the greedy way means that there are a few other useful features that could be written: showing spelling errors in the error list, displaying marks next to the scrollbar for all spelling errors in the file, etc. I'm undecided which approach is simpler, as the state management of being greedy is somewhat complicated.

Anyways, because of this decision and because certain parts of spell checking are really expensive, there is another important thing to consider:

Foreground (UI) and background threads

To get around the expense of doing things greedily, the spell checker runs as much as it can on a background thread, such as the actual spell checking logic. One interesting thing that can't run on the UI thread is the code that determines where the natural text is, meaning comments and strings in code files. To do this, this extension consumes the same classification information (essentially syntax highlighting) that the editor uses to color text in the view. Unfortunately, the new classification interfaces don't really define what it means to be called on a background thread. Even if they did, though, it wouldn't matter for the built-in languages, as nearly every (public) API in VS needs to be accessed on the UI thread. There are exceptions, but they are limited and not entirely well defined in all cases.

So the extension does what it can, but it has to block in small chunks on the UI thread to ask for classification information before spinning of a background thread to go check spellings on those lines.

Put them together, and what do you get?

The issue with large C# files was actually due to trying to figure out what parts of the file are comments and strings and not the spell checking itself. As it turns out, the C# colorizer, wrapped by editor shims in order to produce classification information, had an assumption that there was really only one component consuming that information, which is a perfectly valid assumption in the pre-VS2010 world. Moreover, that interface is still the pre-VS2010 IVsColorizer, so the issue is basically that the editor is breaking an unspecified/assumed contract of the old behavior.

Luckily, on not-too-huge files, a cache in the C# colorizer would cover up the issue. However, the cache only worked for so many lines, so once you have more than 256 lines of multi-line statements, you'd end up in a nasty loop where (simplified):

The spell checker asks for classification information over the entire file.
All the multi-line statements in the file are marked as dirty by the C# colorizer and it sends out an event to inform consumers.
The spell checker goes back through those lines and asks for classification information again (if you'd commented-out or commented-in a section of code, it needs to check those lines again).
All the multi-line statements in those areas are marked as dirty.
Repeat at step #3.

Work around?

Not a simple one, unfortunately: Michael hand-wrote a simplified C# parser that understands comments, strings, and everything else. It's a rather elegant and clean piece of code, which is pretty representative of Michael's coding style, but the most elegant solution would have been to not have to write a parser :) One of the big promises of the new editor is that it exposes a lot of this information specifically so people don't have to do things like this.

(Extension authors) What should I do to avoid this?

It's not something to be terribly worried about, unless you have an extension doing something similar: asking to classify the entire file and responding to classification changed events by re-classifying. If you are just consuming classification information on a lazy basis (e.g. on a line when it changes), you shouldn't run into this.

The underlying bug in that colorizer has been fixed in our internal builds of the product, so it'll certainly make it in to future versions, but it won't make it into QFE form or anything like that. After all, the only known repro is with (a now defunct version of) this spell checker.

If you do run into the issue, though, please let us know, and we can try to help you out with a workaround.

Q&A: ITextSnapshot.GetText()

Noah Richards — Tue, 13 Jul 2010 22:25:00 GMT

(This is part of the Q&A Series)

This question comes from Cameron Peters, from the previous Q&A on read-only regions:

How expensive, relatively is it to call Snapshot.GetText? I have a classifier/tagger that works well with small files (under 100K), but which bogs down as the file goes beyond that, and I'm wondering if my generous use of GetText() could be part of the problem. Many of the sample classifiers (on which I based my work), operate this way. For instance, the SmartTag Walkthrough at http://msdn.microsoft.com/en-us/library/ee334190.aspx uses this line of code in OnLayoutChanged():
if (!snapshot.GetText().ToLower().Equals(e.OldSnapshot.GetText().ToLower()))
...is there a better way to do this sort of thing?

The answer is that you should never use this method. Really. Jack, our architect, wanted to remove the method sometime after the VS2010 CTP, but we didn't want to break people already writing extensions against the editor. Oh, and we had an editor to finish :)

I'll follow up to get the sample changed so that we aren't essentially telling people to use a method that we're telling people not to use, so sorry about that.

The longer story: specificity

The more drawn out answer is that there are extremely few cases where it is a good idea to evaluate* the entire buffer in one go. You can nearly always be more exacting about exactly which parts of the buffer you are curious about.

*I do mean "evaluate". The buffer is stored in a piece tree, and sticking it all in a single string involves the cost of walking the tree and re-assembling the string. Not only is there a performance penalty from re-constituting the string, but a string that can hold the entire buffer also needs to be allocated in one sequential chunk, so you risk an OutOfMemoryException when contiguous free memory is getting tiny.

This sample is an interesting one. I imagine it was written this way for simplicity, as the "real" solution that I would use is slightly more complex. Well, the solution I imagine the sample will change to is just to remove that code, but if you really wanted to a) handle layout events but b) ignore layouts caused by just case changes, I would:

In addition to listening for layout changes, listen to ITextBuffer.Changed events.
These events are delivered with new/old spans and text. To be the best editor citizen you can:
1. Compare the span length first (since the string properties aren't created until evaluated), 1. Then compare the strings (ignore case) only if the lengths match.
2. To be a really good citizen, consider changes larger than some size to always be "real" changes.
3. Never ever write ToLower().Equals(), preferring to use the ignore case comparison routine (so you don't create another copy of the entire string).
4. Even better – only look at changes that intersect spans you care about.
When the layout change event comes around, see if there were any "real" changes, and only event over those changes.
Also, in the layout changed handler, only respond to changes in the NewOrReformattedLines (or NewOrReformattedSpans) collection.

Of these, #2.4, #3, and #4 are all about being minimal and only doing work when absolutely necessary. #2.1-3 are more general performance considerations that are probably less important.

What about a Span from 0 to `ITextSnapshot.Length`?

You'll see this oftentimes when raising changed events from taggers or classifiers. I do it in a few of my extensions and samples.

The answer here is a bit less well-defined. The editor components that consume taggers and classifiers tend to handle these situations without issue because they only look at the parts of the changed event that they care about, like what's visible on the screen currently. This isn't true of all editor components though; the outlining manager, for example, has to keep track of the entire file all the time, to handle the state of collapsed regions.

In general, like most performance issues, the answer is a) wait until you actually know you have a problem, and then b) measure to figure out exactly what is causing the problem. You may find out that something that you expected to be expensive really isn't, or something you expected to be really quick really is. For me, coming from a mostly C++ development experience in college, I'm still surprised every once in awhile that various complicated-looking pieces of managed code aren't performance problems, and it's hard to break the habit of prematurely optimizing those.

...but isn't your earlier advice premature optimization?

Erg. Yeah, sorta. You can look at advice like this in two ways.

First, you can consider only the practical outcome. Editor extensions that handle changes in a minimal way will very likely be more efficient than extensions that don't, except in the case that determining the minimal set of changes is more expensive than handling things more broadly (which is essentially why I have extensions/samples that create spans from [0, ITextSnapshot.Length)). Likewise, it's very possible that these extensions would have been fast enough with the simpler, broader approach.

The other way is to think of it as a qualitatively different way of writing the extension. In some way, it's like the difference between "polling" (is the data there yet? is the data there yet?) and listening for events. One may be faster than the other in some circumstances, but the point is that you understand the data flow differently depending on the approach. In the above example, handling buffer change events directly, to see which should affect a given smart tag, is a different way of thinking about the underlying problem of handling user-generated changes than trying to figure out that information at layout time.

Of course, the first is more practical, so that's the one you should probably concentrate on :) This article was really just for entertainment, then, unless you are using ITextSnapshot.GetText() and it is causing performance problems.

One last thought: parsers

The place where this breaks down is when you have a parser that only works over full files, so even if you just insert a single character on a single line, it still needs to reparse the world.

I know that "use a different parser" isn't really the most tractable answer, so the best you can do in that case is to throttle how often you parse. That's an answer for a whole different post, though, so stay tuned to the blog if you are interested about that type of problem.

Editor fundamentals: Push vs. Pull

Noah Richards — Thu, 08 Jul 2010 17:48:00 GMT

(This is a new series I plan to write in occasionally, where I'll talk more generally about some of the design fundamentals of the editor and best practices for extensions)

One of the things I learned early on, probably incorrectly, is that you can look at how components communicate and basically split the common patterns into two camps.

In the first, one of the components pushes data out; it knows when it has it, and it informs everyone who wants to know (by registration or just a priori relationships) about said data. This is the (roughly) the model of text messaging, where you have messages pushed out to your phone when they are sent and you push them out to other phones when you send them.

In the other, components ask for data when they need it; they know when they need to consume it, and know when they need to ask. This is the model we are all used to when browsing the web: when you want information, you go out and fetch it. The internet doesn't push data to you, for the most part.

Among the latter camp, there also seems to be two primary splits; the first is "polling", which exemplifies just how annoying the English language can be. It's pronounced exactly the same way, and the concept actually always mixes with the more general idea of "pulling" data in my brain, but it does have a specific meaning when I think about it. In polling, the person asks for data over and over again, not necessarily knowing when it changed. HTTP is mostly polling, though does support various caching-related headers to at least reduce the amount of polling you'd need to do to stay up-to-date with a page.

Instead of that, there is also the event-driven route, where the client doesn't push the actual data, but just notifications that the data may be different in some way or the actual updated data.

I'm sure there are real terms for all these, and that I've horribly misconstrued some important points. My apologies for that.

This simplified view of the world, though, is enough for me to talk about what I really wanted to talk about, and that is this:

The old editor was a push world. The new editor is a pull/event world.

Old editor: central storage

If you've used markers in the old editor or read the article I posted comparing markers in VS2008 to tracking spans in VS2010, you'll have a pretty good idea of what to expect of the various services you'd get in the old interfaces.

With only a few exceptions, the editor acts like a large data repository. Clients, usually language services, push things like markers, outlining regions, and completion items (intellisense) to the editor. In terms of "extension points" in the old editor, mostly features that you imagine languages providing, nearly every one was some piece of information being pushed into the editor, to store and (at least partially) own.

The furthest one from this would be colorization, where the editor requests that information on-demand, but even that has a central storage component, in that languages can request line state be kept by the editor for each line in the file.

The API for these extension points is fairly natural and simple. Markers are something of a one-thing-fits-all, where markers give you the ability to track changes, place adornments like breakpoints, put glyphs in the indicator margin, mark regions as read-only, and provide help and tooltips. You figure out what things you want to be in the editor, and then you push it out to the editor. It'll stay put until the text it marks is deleted, essentially, as the editor tracks how it moves and when it should go away.

The downsides

For many of these, then, the editor was just a glorified list, with custom collection APIs (adding, removing, iterating) and some event-like capabilities like marker clients, which are informed when markers are moved or invalidated. But it isn't a very specialized list, being that it needs to serve fairly general needs, so the APIs are neither consistent nor very rich.

One of the interesting patterns that cropped up, looking at the usage of these APIs, is that many languages tended to be storing copies of the same data. Take outlining, for example. Many languages created markers for outlining regions, which is not required as part of the outlining API, so they could track the way the outlining regions changed through buffer edits. Others kept custom collections that more closely matched their language models, so it was easier to update that list as those models changed. To update the editor outlining regions, then, they would iterate over their own collections and the editor's regions simultaneously, noting which regions needed to be added or removed. It wasn't uncommon for some single piece of information, like the extent of an outlining region, to be stored in three or four different places.

And the last issue was that there wasn't really an opportunity for lazily computing this information, as there was no hint that the editor needed to evaluate the information in a specific region of the file. Language services were generally good enough to do work on idle as to not block the user, but there wasn't a good opportunity to avoid work that the user may not care about just now. That sounds vague, I know, but it should make more sense after explaining how the new editor does it.

I'm not really sure that these issues were unavoidable, but some of them seem inherent stumbling blocks of the push approach. By choosing between (a) forcing your data store into a component you have no design control over or (b) duplicating your data twice, you're probably going to pay in either resource usage (CPU time or memory) or difficulty in accomplishing the task at hand.

New editor: decentralization

The model in the new editor is that the only thing necessarily stored in the "editor" is the content of the text buffers. Nearly everything else is cache, or only as much state as is needed to be coherent.

Text markers, like visible breakpoints, are a good example of how this works. Clients implement an ITagger<ITextMarkerTag>, which they list as being available to the editor with a MEF-exported ITaggerProvider. The provision of the tagger is on-demand, when the editor determines that the tagger provider matches the declared content type and tag type of a buffer and the component requesting tags (usually some component that is created per-text view, also matching against content type and text view roles).

A tagger has a method, GetTags, and an event, TagsChanged. When something in the editor wants to know about text markers in a given area, they'll call GetTags, and then assume that the information is valid until the buffer changes around that area or until the tagger raises the TagsChanged event.

(The call to GetTags is indirect, through an ITagAggregator<ITextMarkerTag>, but that's incidental to the point.)

Since most view-level components only ask about lines as they show up or are dirtied in the view (I'll talk more about this in the next installment of this series), the net effect is that the tagger is only asked for areas of the buffer when the user needs that information.

A lot of extension points are accessible through tagging, somewhat similar to markers, in a sense. Some do have a bit of extra state that the editor does manage, such as outlining regions. These are provided through tagging, but the actual collapsed state is stored in the editor, since it is managed across multiple providers and the state can be different in any number of text views over the same buffer. But that is (literally) view-specific state, and the stuff we consider buffer-level model, the collapsible regions themselves, are owned by the taggers that provide them.

There are a few other upsides to this approach, relative to the push model:

API like this lends itself to lazy computation, as the extension knows exactly when the data is needed. As an example, a few people internally have played around with adornments to replace things that represent colors in source files (hex color values in CSS, Colors and Brushes in WPF, things like that). Because these tend to be self-evident, these extensions don't need to walk the file or even listen to buffer changes. All they do is respond for requests for information as they are received by scanning the text and seeing if they have any applicable information.

You could accomplish this in a hacky way with the old editor markers, say by tracking what parts of the view are visible at any point in time and only pushing out information that matches that part of the view. It would be ugly, though, and unnatural.

Also, you don't need to pay to store everything twice if you decide to keep data in a format better fitting your own needs. While the editor may keep a cache of some things, it generally isn't substantial. The most amount of cached information is the view, which keeps visible lines around (for as long as they are visible), and visible adornments, which you can think of as the temporary manifestations of these underlying data components.

The downsides

There are downsides here, as well. No silver bullet or magical solution.

First, designing components in this way seems to come less naturally to people. Maybe that's just because people are used to the push model of providing data, or maybe it is really because most people's mental model of data flow doesn't work like this. It's especially common for people providing adornments to treat it as if you need to push the adornment out to the view (instead of providing the adornment when requested), especially since the API actively lends itself to this (with methods like AddAdornment and RemoveAdornment on IAdornmentLayer), but I see that entirely as a problem for the editor to fix by providing more obvious APIs, better documentation, and a larger body of samples and templates. Adornments are an especially confusing topic, which is why I'm going to cover that specifically in the next part of this series.

Second, some extensions don't care about making their own data structures, and the overhead of doing so makes things less simple. We've tried to mitigate this for tagging, unfortunately without being obvious about it, by providing a SimpleTagger<T> type. It implements the tagging interface, so you can return it from an ITaggerProvider, and you can use it like a simple list. That's still more overhead (and certainly less obvious) than an API that forces/provides a simple Add/Remove push model.

Third, things like GetTags tend to be moderately chatty, though not necessarily more so than the old interfaces did, since there was a decent amount of back and forth around enumerating markers/outlining regions/etc. and adding/removing them to stay in sync with external lists. For these interfaces, the chattiness is that the editor doesn't do much caching or sharing at the tag aggregation level, so each consumer gets its own ITagAggregator, and each call for tags from each consumer results in a call to GetTags. As such, expensive lazy computation without any sort of caching at the tagger level isn't a great idea, as you'll pay that cost per-consumer instead of per-update. This is something we have ideas for improving, but we're mostly waiting to see if it will become a problem in practice.

Specifics to generalizations

I'm not sure how much of this applies to the general issue of push/pull and poll/event. After working with it for a few years, I have to say I'm pretty happy with the general outcome, and the problems that we aren't having.

The biggest issues we are having are essentially from the confusion department. Interfaces are non-obvious, documentation is spotty, samples are sparse, editor bloggers are about as bright as a turnip (hey! that's not nice), MEF is a bit too far on the magical side (read: hard to debug), certain things cry out for better extension points, and the list goes on and on.

The only thing I can really say to this is that I think that developing extensible applications really has to be considered an ongoing enterprise. I don't think it would be really possible to, in the 2-4 years it took to build the new editor (depending on how you count), create an editor with feature parity with the one that has been in usage for at least the last decade and design a perfect extensibility layer. I'd also like to think that something is usually better than nothing, though there is that gigantic rat's nest of compatibility.

(You can't see me right now, but when I hear or even type the word "compatibility", I stick my fingers in my ears and yell LA LA LA LA until the thought goes away)

I do think one of the things that helped us do as well as we did is that the extensibility API we designed wasn't really the "extensibility" API; it was the API for the editor, which happens to be publicly accessible. I'll continue to sing the praises of that story until the day men in suits come to collect me.

A quick update

Noah Richards — Tue, 22 Jun 2010 05:11:02 GMT

Sorry for (another) long hiatus, again. I've been pretty busy, the last few weeks especially, working on fixing bugs and some interesting internal projects that may make their way to the public eye soon-ish (like in the next few months soon-ish, which probably isn't that soon).

In the interim, I wanted to note that I just pushed out an updated version (2.2) of Go To Definition. The notable part of the change is that it moves the handling to mouse-up instead of mouse-down, meaning that it should play nicely now with word selection logic and drag/drop. Source changes, as always, can be viewed on github.

Also, if you are currently using VS2010 RTM and are finding issues, please file bugs on Connect. A lot of the bugs I'm fixing right now are filed on Connect, so it's your chance to find something in VS to get changed. You can always email me directory, through this blog, but it'll be easier to track and get others to vote on issues that you've opened publicly through Connect.

Finally, completely unrelated to work: if you aren't a Microsoft employee and you'd like to get an idea of some of the strangeness that goes on here, take a gander at Bug Bash. Microsoft employees should take a look, too, as long as they don't mind being reminded of some of the ridiculous-ities of work.

Q&A: Read-only regions

Noah Richards — Tue, 04 May 2010 17:30:00 GMT

This question was asked recently on the (internal) editor discussion alias:

Is it at all possible to make parts of the text buffer read-only? Could I, for example, mark certain spans as not modifiable, so that the user wouldn't be able to change their contents?

The short answer is yes; in fact, marking regions of the buffer as read-only is the primary model of controlling the read-only-ness of the buffer, and doing something like setting the entire buffer read-only is a special case of that (marking the region that covers the entire buffer as read-only).

The general model

The API for creating read-only regions looks very much like creating regular edits. The entry point is to create a read-only region edit (ITextBuffer.CreateReadOnlyRegionEdit), which is what you use to make the actual edits of adding or removing read-only regions. To answer the original question, here's an example of how to make an entire buffer read-only:

ITextBuffer textBuffer;
IReadOnlyRegion region;

using (IReadOnlyRegionEdit edit = textBuffer.CreateReadOnlyRegionEdit())
{
    region = edit.CreateReadOnlyRegion(new Span(0, edit.Snapshot.Length));
    edit.Apply();
}

When you create (add) a region, you get back a handle to the region, which you'll need to hold on to if you ever want to remove it again, like this:

using (IReadOnlyRegionEdit edit = textBuffer.CreateReadOnlyRegionEdit())
{
    edit.RemoveReadOnlyRegion(region);
    edit.Apply();
}

In case you missed it, the (intentional) side-effect of this design is that only the "owner" who creates a read-only region can remove that region. This means that one person can mark parts of or the entire buffer read-only, thus preventing anyone else from editing it (as that person expects), without any way for other people to pull that protection out from under the original owner's proverbial feet.

To snapshot or not to snapshot

Sometime in the last year, we got reports that read-only regions were causing performance issues in general C# debugger stepping scenarios.

I don't remember the exact details, but the gist is that the C# language service was setting and unsetting read-only-ness on every step. There wasn't a simple way to determine that it was a "step" and not just a blanket "start running the debugger again", so it was a rather costly expense for what was essentially too short-lived for the user to even notice (or at least shouldn't be noticeable, assuming things are nice and fast).

At the time, generating new read-only regions was slow because each read-only region edit create a new ITextSnapshot for that buffer, with similar costs to making an edit. In this case, it was setting read-only regions on more than a single file, so I think it was more like making an edit on lots of files simultaneously.

The question, at the time, was, "why does the editor need to generate a new snapshot when read-only regions change?" It's an interesting design choice, to say the least. As I understand it (I wasn't on the team at the time, so this is hearsay), people thought there would be utility in being able to ask, "On snapshot foo, was region bar read-only?", to see what the read-only state of the buffer was historically, much like how snapshots let you look at the buffer contents historically.

As it turns out, though, that's not especially useful information to have. There is some symmetry there with asking what edits happened on old snapshots (technically versions), but there's isn't anything you can really do with that information. You can only edit the current version of the buffer, so the only real question people need to ask is, "On buffer foo, was region bar read-only?".

So, Jack changed read-only regions so that they are conceptually and literally buffer-specific instead of snapshot-specific, and most of that performance issue wasn't anymore. There were actually other changes made, in the language service, that made this change mostly unnecessary for that specific scenario, but it was still the change that we wanted to make.

Dynamic read-only regions

The other late entry to the game was the concept of dynamic read-only regions. This one was written by Sergei, at least in part to support (VS2008 and previous) markers, which can prevent edits over the span of text they cover.

These regions are inserted and removed just like regular ol' read-only regions, with one extra argument in CreateDynamicReadOnlyRegion: a DynamicReadOnlyRegionQuery. The contract for that callback is fairly simple; it's told whether or not the query ("is this read-only?") is happening as part of an edit or just as a simple request, and it returns true or false.

One reason for including information about whether the request is an edit is to use this feature for something like source code integration's check out on edit feature. You could imagine, for files that aren't yet checked-out, putting a dynamic read-only region over the file, returning true when asked about read-only-ness for non-edits, and then attempt to perform the checkout on edit.

This also leads to another guiding principle of read-only regions: if you need to make an edit, never ask about read-only regions before making the edit. Instead, try to make the edit and handle failure gracefully (the various methods on ITextEdit return whether or not that part of the edit succeeded). There are methods for asking about which spans in a buffer/snapshot are read-only, but you shouldn't use these if you intend to make an edit with the knowledge. As the saying goes, never ask permission, as for forgiveness (or, in the editor's case, be prepared to deal with the punishment).

Extending extensions

Noah Richards — Fri, 30 Apr 2010 17:30:00 GMT

If you'd ever taken a peek at the code for the Spell Checker extension before a couple weeks ago, you may have noticed that there were some definition interfaces intermingled with the various implementation classes. One such example is the NaturalTextTag, which the spell checking logic aggregates to know what parts of a text buffer to spell check. The extension has two defined; one for plaintext files, which says "spell check the whole file", and one for code files, which says "spell check all comments and strings".

However, the real intent was that this tag could be produced by other extensions, for other languages, like determining which portions of an HTML page should be checked, or, say, Markdown files. Essentially, the Spell Checker should be an extensible extension, no different than the many other extensible things in the editor. After all, there's no real reason to believe that the editor provides every extensibility point that you could ever need, or that there isn't a need for extensions themselves to interoperate in ways that we didn't foresee.

The spell checker is a great example of this. If spell checking was built-in, it would (hopefully) have lots of extensibility points: plugging in custom dictionaries, being able to modify behavior depending on the type of file being edited, adding new spelling actions other than the default, etc. So why should it be any different if an extension provides spell checking?

The problem, essentially, comes down to contracts. For the sake of simplicity, we'll just think of these as types. We need a way for these extensions to agree on types, like INaturalTextTag, which means that they both need to essentially share an assembly. Ideally, they'd also both be distributable via VSIX file, which precludes actually sharing installed assemblies, to a degree, since you don't get control over where your assemblies end up on disk.

Sharing type definitions

In the product itself, we've shared out some definition assemblies that anyone can add a reference to and use. The various built-in ITag types, for example, are all well-known, so any extension can provide its own outlining logic, or errors/squiggles, or syntax highlighting.

The reason this works without requiring every extension to ship a copy of the editor definition assemblies is that these assemblies are essentially already loaded by the time your extension is loaded (more correctly, Visual Studio knows where to find them when it comes time to load them). Go go magic managed code and all that.

Binding paths

One of the features of Visual Studio that I've used previously to work around issues with loading custom tag types (see the last issue on this page) is actually a much more generally useful way of adding a directory to the list of paths that Visual Studio considers when looking for assemblies to load (the BindingPaths registry key). This fixes the issue of custom tag types, as it makes it so the MEF component loader can find the assembly to load for the type information it has saved in the component model cache.

The issue of sharing definition assemblies is effectively the same issue, then.

When you think of assembly sharing, there are basically two steps:

The assembly needs to be available at build time, so you can compile your extension with the correct type references.
The assembly needs to be available at run time, so you can load your extension that references these types.

We usually conflate the two, but they truly are distinct.

Overall workflow

So the workflow here is fairly simple:

First, you need the physical definition assembly as a reference to build against. This may mean building and checking in a version of the assembly to your source control, or taking advantage of something like git's submodule support to link to the live source from which the definition assembly is built. Also, you want to be sure to not include that definition assembly in your VSIX. It may not actually be hugely problematic if you do (I never really tested this out), but you certainly won't need it.

Then, you create a reference from your VSIX to the VSIX you are depending on. In the .vsixmanifest designer this is fairly simple; in the References section, simply click the Add Reference button and add the information you need (if you have the extension already installed, it'll let you select it instead of typing in the name/ID manually). The only tricky part is picking the min/max version number. For the spell checker extension, I'm softly guaranteeing that I won't update the definition assemblies at least until the next major version number (3.0), so I'd use 2.999 as the max version number. Picking an existing minor version number as the max would not be a great idea, since I update these fairly frequently (five times or so last Friday, during a bug bash at work).

So now, when the user wants to install your VSIX, he has to first install whatever it depends on (I hope this becomes a more automatic feature in the future, instead of requiring the user to manually install dependencies). That means that, assuming the dependencies play nicely with binding paths, your extension can depend on the types it needs be available to it at runtime.

As of now, I don't know of any extensions on the gallery that actually extend the spell checker, though I do know of one person who was working on it, as he was the motivation for figuring out how to do all this. I have heard questions, like this tweet from Jared Parsons about wanting to have a per-project dictionary, which would be well served by an extension that would keep a per-project dictionary file and ensure it is added and updated in source control (for Jared's or my sake, TFS or git, depending on what we're working on).

If you are interested in creating an extension to the spell checker or creating your own extensible extension, feel free to ask me for help. I'm very interested to see what, if anything, people do in this space, especially since one of my hopes for tagging is that there would be some amount of shared user-generated tag types for everyone to party on.

One remaining question

The one thing that remains unanswered for me is: what if you want to light up a feature in another extension but not require it always be installed? Specifically, the scenario is this:

If you have Markdown Mode installed and the spell checker installed at the same time, Markdown Mode should enable markdown-specific natural text parsing logic. If you have the spell checker installed by itself, it doesn't have any specific knowledge of markdown files. If you have the Markdown Mode extension installed by itself, it doesn't do any spell checking on its own.

The trick is that I don't want the Markdown Mode extension to require the spell checker extension be installed, I just want it get specific spell checking when both extensions are installed on the same machine.

I haven't really figured this one out yet. I don't know if Markdown Mode can get away with not shipping the spell checker definition assembly, which is likely half the fault of how MEF is set up in Visual Studio and half the fault of how the editor handles failures.

The issue is that the TagType attribute on tagger providers doesn't use exact matching of types. If a tagger provider says it produces an ISpecificTag, and someone creates an aggregator for IBaseTag from which ISpecificTag inherits, the ISpecificTag tagger provider will created and just work through the magic of covariance.

To do this, though, the logic that matches up taggers needs the actual type hierarchy of ISpecificTag to see if it is assignable to an IBaseTag reference. In the case of the spell checker, with INaturalTextTag, it needs to know what that type is.

The answer here is really that Markdown Mode's natural text tagger doesn't care; if the spell checker isn't around and so it's natural text tag's hierarchy isn't available, it just doesn't want to be loaded.

The problem is that when the tag aggregator is matching up tag types, it will try to evaluate the type of the MarkdownMode tagger provider, and it doesn't expect or guard against the exception that will be thrown when the VS MEF-hosting logic can't figure out what type to load. If it did (just catch the exception and move on), then we'd get the effect we're looking for.

So, the only obvious workaround seems to be to include a copy of the definition assembly in Markdown Mode (and add it to the binding path), though that may introduce other problems down the line. Hopefully the issue in the tag aggregator can be dealt with, and so this problem won't be permanent, but it won't be fixed anytime in the immediate future.

Long time no bloggy.

Noah Richards — Mon, 19 Apr 2010 17:30:00 GMT

Been a long time since I've blogged, sorry about that. I won't get too deep into things that have happened since my last post, but here's the short list:

Visual Studio 2010 shipped

Yeah, the obvious one. We (individual developers) actually aren't that involved for the last month or so, but there were a few last minute fixes and activities around the launch of VS to get finished up.

All in all, we shipped on time (where on time means "the last date that we picked to ship, no delaying last-minute issues") and, so far as I know, haven't managed to physically destroy everyone's computer or break anyone with an attached tablet device (again). That's what the RC is for :)

Extension updates galore

I've pushed out some updates in the last few weeks, a ton in the last week or two to the Spell Checker extension.

Fixing bugs for the future

As with everything that has a shipping deadline, you can't fix everything that you'd want to, given infinite time and resources. Around the time that VS2010 shipped, our (the editor team's) triage team went through the bugs that we'd postponed due to resource constraints and relative priority and split out the ones that we really are just not ever going to fix and the ones that we should be fixing.

Since then, I've been fixing lots of little issues that have been bugging me for awhile, which includes everything from misspelled comments and confusing exception messages to silly/stupid little mistakes (like the one where the URL classifier doesn't subscribe to TagsChanged events on any ITagger<IUrlTag>, which at least one person has already hit).

Other random things at work

We're at a stage, between releases, where we step back from working on features and bugs and work on, well, everything else. As part of that, there are a ton of smaller projects going on in the division. One that I'm working on with Michael, a coworker on the editor team (who needs to write new articles in his blog), involves some of the more advanced features of the editor (text view models and the projection system). We'll share more about it in the next few months, along with blog posts on the what and how.

What's to come?

I haven't been writing too many new extensions these days, so expect more posts about editor extensibility in the abstract in the near future. Also, I'm always open to taking topic ideas, so send me an email or post a comment if there is something you'd like to see written about.

Also, if you have any feedback about Visual Studio 2010, please either open bugs on Connect, ping me on twitter (@noahsmark), or send me an email. The Connect bugs would be the best way to track the status of any bugs you file, but anything sent to me should find its way to the correct team.

Letters from the (VS) Editor

Moving on

Code Snippet: Ensuring a file is in a project

Editor fundamentals: Text-Relative Adornments

The adornment "manager"

Adding adornments to the layer

Data sources

Layout + tagging

Other considerations

Spell Checker Update - Perf bug on large C# files

Somewhat greedy spell checking

Foreground (UI) and background threads

Put them together, and what do you get?

Work around?

(Extension authors) What should I do to avoid this?

Q&A: ITextSnapshot.GetText()

The longer story: specificity

What about a Span from 0 to ITextSnapshot.Length?

...but isn't your earlier advice premature optimization?

One last thought: parsers

More questions?

Editor fundamentals: Push vs. Pull

Old editor: central storage

The downsides

New editor: decentralization

The downsides

Specifics to generalizations

A quick update

Q&A: Read-only regions

The general model

To snapshot or not to snapshot

Dynamic read-only regions

More questions?

Extending extensions

Sharing type definitions

Binding paths

Overall workflow

One remaining question

Long time no bloggy.

Visual Studio 2010 shipped

Extension updates galore

Fixing bugs for the future

Other random things at work

What's to come?

What about a Span from 0 to `ITextSnapshot.Length`?