Delayed Document Loading

When a user reopens a Visual Studio solution, most of the associated documents are not loaded immediately. The document window frame is created in a pending-initialization state, and a placeholder document (called a stub frame) is placed in the Running Document Table (RDT).

Your extension may cause project documents to be loaded unnecessarily by querying elements in the documents before they are loaded. This can increase the overall memory footprint for Visual Studio.

Document Loading

The stub frame and document are fully initialized when the user accesses the document, for example by selecting the tab of the window frame. The document can also be initialized by an extension that requests the document’s data, either by accessing the RDT directly to acquire the document data, or accessing the RDT indirectly by making one of the following calls:

• The window frame show method: Show.

• The window frame GetProperty method GetProperty on any of the following properties:

  • VSFPROPID_DocView

  • VSFPROPID_ViewHelper

  • VSFPROPID_DocData

  • VSFPROPID_AltDocData

  • VSFPROPID_RDTDocData

  • VSFPROPID_SPProjContext

If your extension uses managed code, you should not call GetDocumentInfo unless you are certain that the document is not in the pending-initialization state, or you want the document to be fully initialized.. This is because this method always returns the doc data object, creating it if necessary. Instead, you should call one of the methods on the IVsRunningDocumentTable4 interface.

If your extension uses C++, you can pass null for the parameters you don’t want.

You can avoid unnecessary document loading by calling one of the following methods before you ask for the relevant properties: before you ask for other properties.

• GetProperty using VSFPROPID_PendingInitialization.

• GetDocumentFlags. This method returns a _VSRDTFLAGS4 object that includes a value for RDT_PendingInitialization if the document has not yet been initialized.

You can find out when a document has been loaded by subscribing to the RDT event that is raised when a document is fully initialized. There are two possibilities:

• If the event sink implements IVsRunningDocTableEvents2, you can subscribe to OnAfterAttributeChangeEx,

• Otherwise, you can subscribe to OnAfterAttributeChange.

The following is a hypothetical document access scenario. A Visual Studio extension want to display some information about open documents, for instance the edit lock count and something about the document data. It enumerates the documents in the RDT using IEnumRunningDocuments, then calls GetDocumentInfo for each document in order to retrieve the edit lock count and document data. If the document is in the pending-initialization state, requesting the document data causes it to be unnecessarily initialized.

A more efficient way of doing this is to use GetDocumentEditLockCount to get the edit lock count, and then use GetDocumentFlags to determine whether the document has been initialized. If the flags do not include RDT_PendingInitialization, the document has already been initialized ,and requesting the document data with GetDocumentData does not cause any unnecessary initialization. If the flags do include RDT_PendingInitialization, the extension should avoid requesting the document data until the document is initialized. This can be detected in the OnAfterAttributeChange(Ex) event handler.

Testing extensions to see if they force initialization

There is no visible cue to indicate whether a document has been initialized, so it can be difficult to find out if your extension is forcing initialization. You can set a registry key that makes verification easier, because it causes the title of every document that is not fully initialized to have the text [Stub] in the title.

In HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0\BackgroundSolutionLoad], set StubTabTitleFormatString to {0} [Stub].