Microsoft.VisualStudio.Extensibility.Editor.md

Microsoft.VisualStudio.Extensibility.Editor

Contents

• AppliesToAttribute
  • DocumentType
• AppliesToPatternAttribute
  • Pattern
  • RelativePath
• DocumentTypeBaseDefinitionAttribute
  • #ctor(documentTypeName,baseDocumentTypeName)
  • Base
  • DocumentType
• DocumentTypeDefinitionAttribute
  • #ctor(name)
  • DocumentType
• EditBatch
• EditResponse
  • #ctor(succeeded,message,documentEditResults,textViewEditResults)
  • DocumentEditResults
  • Message
  • Succeeded
  • TextViewEditResults
• EditorExtensibility
  • #ctor(extensibility,editorHostService)
  • EditAsync(editorSource,cancellationToken)
  • GetActiveTextViewAsync(clientContext,cancellationToken)
• FileExtensionMappingAttribute
  • #ctor(fileExtension,documentType)
  • DocumentType
  • FileExtension
• ITextViewChangedListener
  • TextViewChangedAsync()
• ITextViewChangedListenerContract
  • TextViewChangedAsync()
• ITextViewLifetimeListener
  • TextViewClosedAsync()
  • TextViewCreatedAsync()
• ITextViewLifetimeListenerContract
  • TextViewClosedAsync()
  • TextViewCreatedAsync()
• TextDocumentSnapshotEditResponse
  • #ctor(after,editResult)
  • After
  • EditResult
• TextEdit
  • Range
  • Text
• TextViewChange
  • AfterTextView
  • BeforeTextView
  • DocumentEdits
• TextViewChangedArgs
  • #ctor(beforeTextView,afterTextView,edits)
  • AfterTextView
  • BeforeTextView
  • Edits
• TextViewChangedListener
• TextViewEditResponse
  • #ctor(after,editResult)
  • After
  • EditResult
• TextViewLifetimeListener
• VisualStudioExtensibilityExtensions
  • Editor(extensibility)

AppliesToAttribute type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Describes the conditions under which an extension part should be activated.

See Also

• Microsoft.VisualStudio.Extensibility.Editor.DocumentTypeDefinitionAttribute

DocumentType property

Summary

The document type of an object. Document type is frequently used to target specific languages.

AppliesToPatternAttribute type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Describes the conditions under which an extension part should be activated.

Pattern property

Summary

The glob pattern to match document file path. Glob patterns can have the following syntax:

• to match one or more characters in a path segment ? to match on one character in a path segment ** to match any number of path segments, including none {} to group conditions (e.g. **/*.{ts,js} matches all TypeScript and JavaScript files) [] to declare a range of characters to match in a path segment (e.g., example.[0-9] to match on example.0, example.1, …) [!...] to negate a range of characters to match in a path segment (e.g., example.[!0-9] to match on example.a, example.b, but not example.0) Note: a backslash () is not valid within a glob pattern. If you have an existing file path to match against, consider to use the relative pattern support that takes care of converting any backslash into slash. Otherwise, make sure to convert any backslash to slash when creating the glob pattern.

RelativePath property

Summary

Defines whether the pattern should be applied to the absolute path of a file or to a path relative to the solution folder.

DocumentTypeBaseDefinitionAttribute type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Makes a document type inheriting from a defined base.

Remarks

Example:

[assembly: DocumentTypeDefinitionAttribute("markdown")]
[assembly: DocumentTypeBaseDefinitionAttribute("markdown", baseDocumentTypeName: "code")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".md")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".mdk")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".markdn")]

See Also

• Microsoft.VisualStudio.Extensibility.Editor.DocumentTypeDefinitionAttribute
• Microsoft.VisualStudio.Extensibility.Editor.FileExtensionMappingAttribute
• Microsoft.VisualStudio.Extensibility.Editor.AppliesToAttribute

#ctor(documentTypeName,baseDocumentTypeName) constructor

Summary

Initializes a new instance of DocumentTypeBaseDefinitionAttribute.

Parameters

Name	Type	Description
documentTypeName	System.String	The document type name. Document type names are case-insensitive.
baseDocumentTypeName	System.String	The base document type name. Document type names are case-insensitive.

Exceptions

Name	Description
System.ArgumentNullException	documentTypeName or baseDocumentTypeName is null or an empty string.

Base property

Summary

The base document type name.

DocumentType property

Summary

The document type name.

DocumentTypeDefinitionAttribute type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Declares a new document type.

Remarks

Example:

[assembly: DocumentTypeDefinitionAttribute("markdown")]
[assembly: DocumentTypeBaseDefinitionAttribute("markdown", baseDocumentTypeName: "code")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".md")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".mdk")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".markdn")]

See Also

• Microsoft.VisualStudio.Extensibility.Editor.DocumentTypeBaseDefinitionAttribute
• Microsoft.VisualStudio.Extensibility.Editor.FileExtensionMappingAttribute
• Microsoft.VisualStudio.Extensibility.Editor.AppliesToAttribute

#ctor(name) constructor

Summary

Initializes a new instance of DocumentTypeDefinitionAttribute.

Parameters

Name	Type	Description
name	System.String	The document type name. Document type names are case-insensitive.

Exceptions

Name	Description
System.ArgumentNullException	name is null or an empty string.

DocumentType property

Summary

The document type name.

EditBatch type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.Editing

Summary

Builder for CompoundEditContract, describing a set of state changes that should be made by the process owning the entities to be changed, on behalf of the extension.

EditResponse type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.Editing

Summary

Describes the cumulative result of a call to EditAsync.

#ctor(succeeded,message,documentEditResults,textViewEditResults) constructor

Summary

Initializes a new instance of EditResponse.

Parameters

Name	Type	Description
succeeded	System.Boolean	true if the cumulative operation completed successfully.
message	System.String	Any cumulative error message, null, or Empty if none.
documentEditResults	System.Collections.Generic.IReadOnlyDictionary{Microsoft.VisualStudio.Extensibility.Editor.Data.ITextDocumentSnapshot,Microsoft.VisualStudio.Extensibility.Editor.Editing.TextDocumentSnapshotEditResponse}
textViewEditResults	System.Collections.Generic.IReadOnlyDictionary{Microsoft.VisualStudio.Extensibility.Editor.UI.ITextViewSnapshot,Microsoft.VisualStudio.Extensibility.Editor.Editing.TextViewEditResponse}	Per-document operation results including per document errors and updated ITextDocumentSnapshot
versions.

DocumentEditResults property

Summary

Per-document operation results including per document errors and updated ITextDocumentSnapshot versions.

Remarks

Key of dictionary is the version of the document prior to the edits. After contains the updated document version.

Message property

Summary

Any cumulative error message, null, or Empty if none.

Succeeded property

Summary

true if the cumulative operation completed successfully.

TextViewEditResults property

Summary

Per text view operation results including per text view errors and updated ITextViewSnapshot versions.

EditorExtensibility type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Framework object exposing methods for getting and interacting with ITextViewSnapshots and ITextDocumentSnapshots and performing document edits and other state changes.

Remarks

You can get an instance of EditorExtensibility by calling Editor within an ExtensionPart or Command.

#ctor(extensibility,editorHostService) constructor

Summary

Initializes a new instance of EditorExtensibility.

Parameters

Name	Type	Description
extensibility	Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility	The root extensibility object.
editorHostService	Microsoft.VisualStudio.Extensibility.Editor.IEditorHostService	The editor host service.

EditAsync(editorSource,cancellationToken) method

Summary

Initiates an edit request in the host Visual Studio process, enabling the extension to atomically request one or more ITextDocumentSnapshot edits, caret position changes, or other state changes.

Returns

A response object detailing whether the operation was successful and which ITextDocumentSnapshots and ITextViewSnapshots changed.

Parameters

Name	Type	Description
editorSource	System.Action{Microsoft.VisualStudio.Extensibility.Editor.Editing.IEditBatch}	A service for obtaining editors for requesting changes to a IEditable`1 object, such as ITextDocumentSnapshot.
cancellationToken	System.Threading.CancellationToken	Cancels a pending request.

Remarks

Edit request is sent to Visual Studio IDE, where it succeeds only if the object being edited hasn't changed since the version the request was made one. If the document has changed, the change may be rejected, requiring the extension to retry on a newer version.

Edits are applied atomically. The best practice is to do all changes that should occur within a narrow time frame within a single EditAsync() call to reduce the likelihood of unexpected behavior arising from user edits, or language service actions that occur between edits.

GetActiveTextViewAsync(clientContext,cancellationToken) method

Summary

Gets the currently focused ITextViewSnapshot in the host Visual Studio process.

Returns

An instance of ITextViewSnapshot or null.

Parameters

Name	Type	Description
clientContext	Microsoft.VisualStudio.Extensibility.Definitions.IClientContext	The client context, usually passed to command handlers.
cancellationToken	System.Threading.CancellationToken	Cancels the request.

Remarks

Can return null if the clientContext references a version of text view that is sufficiently old so as to no longer be cached.

FileExtensionMappingAttribute type

Namespace

Microsoft.VisualStudio.Extensibility.Editor

Summary

Associate a document type to a file extension.

Remarks

Example:

[assembly: DocumentTypeDefinitionAttribute("markdown")]
[assembly: DocumentTypeBaseDefinitionAttribute("markdown", baseDocumentTypeName: "code")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".md")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".mdk")]
[assembly: FileExtensionMappingAttribute("markdown", fileExtension: ".markdn")]

See Also

• Microsoft.VisualStudio.Extensibility.Editor.DocumentTypeDefinitionAttribute
• Microsoft.VisualStudio.Extensibility.Editor.DocumentTypeBaseDefinitionAttribute
• Microsoft.VisualStudio.Extensibility.Editor.AppliesToAttribute

#ctor(fileExtension,documentType) constructor

Summary

Initializes a new instance of FileExtensionMappingAttribute.

Parameters

Name	Type	Description
fileExtension	System.String	The file extension. File extensions are case-insensitive.
documentType	System.String	The document type name. Document type names are case-insensitive.

Exceptions

Name	Description
System.ArgumentNullException	fileExtension or documentType is null or an empty string.

DocumentType property

Summary

The document type name.

FileExtension property

Summary

The file extension.

ITextViewChangedListener type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.UI

Summary

Extensibility point for listening for ITextViewSnapshots to be changed.

TextViewChangedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is changed.

Parameters

This method has no parameters.

ITextViewChangedListenerContract type

Namespace

Microsoft.VisualStudio.RpcContracts.Editor

Summary

RPC contract for a listener that is notified when text views are changed.

TextViewChangedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is changed.

Parameters

This method has no parameters.

ITextViewLifetimeListener type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.UI

Summary

Extensibility point for listening for ITextViewSnapshots to be opened and closed.

TextViewClosedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is closed.

Parameters

This method has no parameters.

Remarks

Special scenarios:

• Document type changes from a matching document type to an unmatching, such as when the user changes the file extension, are considered 'text view closes' for the purposes of this API.

TextViewCreatedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is opened.

Parameters

This method has no parameters.

Remarks

Special scenarios:

• Document type changes from an unmatching document type to a matching, such as when the user changes the file extension, are considered 'text view creations' for the purposes of this API.
• This API will be called for all already open text views when an extension is hot loaded in the middle of an existing session.

ITextViewLifetimeListenerContract type

Namespace

Microsoft.VisualStudio.RpcContracts.Editor

Summary

RPC contract for a listener that is notified when text views are opened and closed.

TextViewClosedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is closed.

Parameters

This method has no parameters.

Remarks

Special scenarios:

• Document type changes from a matching document type to an unmatching, such as when the user changes the file extension, are considered 'text view closes' for the purposes of this API.

TextViewCreatedAsync() method

Summary

Called when an ITextViewSnapshot with matching document type is opened.

Parameters

This method has no parameters.

Remarks

Special scenarios:

• Document type changes from an unmatching document type to a matching, such as when the user changes the file extension, are considered 'text view creations' for the purposes of this API.
• This API will be called for all already open text views when an extension is hot loaded in the middle of an existing session.

TextDocumentSnapshotEditResponse type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.Editing

Summary

Describes the outcome of a call to EditAsync for changes to a particular ITextDocumentSnapshot in the host Visual Studio process.

#ctor(after,editResult) constructor

Summary

Initializes a new instance of TextDocumentSnapshotEditResponse.

Parameters

Name	Type	Description
after	Microsoft.VisualStudio.Extensibility.Editor.Data.ITextDocumentSnapshot	The ITextDocumentSnapshot version after the changes were applied.
editResult	Microsoft.VisualStudio.RpcContracts.Editor.EditResult	The result of the edit operation.

After property

Summary

The ITextDocumentSnapshot version after the changes were applied.

EditResult property

Summary

The result of the edit operation. Success if all changes were applied successfully to the target ITextDocumentSnapshot.

TextEdit type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.Editing

Summary

A list of changes applied to a ITextDocumentSnapshot.

Range property

Summary

The range to replace. Can be zero length.

Text property

Summary

The new text to insert.

TextViewChange type

Namespace

Microsoft.VisualStudio.RpcContracts.Editor

Summary

RPC contract representing a TextViewChangedArgs.

AfterTextView property

Summary

The state of the ITextViewSnapshot after the change.

BeforeTextView property

Summary

The state of the ITextViewSnapshot before the change.

DocumentEdits property

Summary

The set of edits made to the document during this change.

TextViewChangedArgs type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.UI

Summary

Arguments for ITextViewChangedListener.

#ctor(beforeTextView,afterTextView,edits) constructor

Summary

Creates a new instance of TextViewChangedArgs.

Parameters

Name	Type	Description
beforeTextView	Microsoft.VisualStudio.Extensibility.Editor.UI.ITextViewSnapshot	The state of the ITextViewSnapshot before the change.
afterTextView	Microsoft.VisualStudio.Extensibility.Editor.UI.ITextViewSnapshot	The state of the ITextViewSnapshot after.
edits	System.Collections.Generic.IReadOnlyList{Microsoft.VisualStudio.Extensibility.Editor.Editing.TextEdit}	A list of changes applied to the text document.

AfterTextView property

Summary

The state of the ITextViewSnapshot after the change.

BeforeTextView property

Summary

The state of the ITextViewSnapshot before the change.

Edits property

Summary

A list of changes applied to the text document.

TextViewChangedListener type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.UI

Summary

Wrapper object that converts RPC types to C# types.

TextViewEditResponse type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.Editing

Summary

Describes the outcome of a call to EditAsync for changes to a particular ITextViewSnapshot in the host Visual Studio process.

#ctor(after,editResult) constructor

Summary

Initializes a new instance of TextViewEditResponse.

Parameters

Name	Type	Description
after	Microsoft.VisualStudio.Extensibility.Editor.UI.ITextViewSnapshot	The ITextViewSnapshot version after the changes were applied.
editResult	Microsoft.VisualStudio.RpcContracts.Editor.EditResult	The result of the edit operation.

After property

Summary

The ITextViewSnapshot version after the changes were applied.

EditResult property

Summary

The result of the edit operation. Success if all changes were applied successfully to the target ITextViewSnapshot.

TextViewLifetimeListener type

Namespace

Microsoft.VisualStudio.Extensibility.Editor.UI

Summary

Wrapper object that converts RPC types to C# types.

VisualStudioExtensibilityExtensions type

Namespace

Microsoft.VisualStudio.Extensibility

Summary

Editor provided extension methods for acquiring VS extensibility points.

Editor(extensibility) method

Summary

Gets an instance of the EditorExtensibility point.

Returns

Editor extensibility.

Parameters

Name	Type	Description
extensibility	Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility	The root VisualStudioExtensibility instance.