Compartilhar via


Delayed document loading

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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, which 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:

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:

The following example is a hypothetical document access scenario: A Visual Studio extension wants 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 accessing a document 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 _VSRDTFLAGS4.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 _VSRDTFLAGS4.RDT_PendingInitialization, the extension should avoid requesting the document data until the document is initialized. This initialization can be detected in the OnAfterAttributeChange(Ex) event handler.

Test 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\14.0\BackgroundSolutionLoad, set StubTabTitleFormatString to {0} [Stub].