Skip to content

Commit 4226e5e

Browse files
tfosmarktfosmark
authored
Merge pull request #2460 from changeworld/patch-51
Delete unnecessary spaces
2 parents 9623470 + 1499a10 commit 4226e5e

File tree

1 file changed

+129
-129
lines changed

1 file changed

+129
-129
lines changed

‎docs/extensibility/adapting-legacy-code-to-the-editor.md

Lines changed: 129 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -2,141 +2,141 @@
22
title: "Adapting Legacy Code to the Editor | Microsoft Docs"
33
ms.date: "11/04/2016"
44
ms.topic: "conceptual"
5-
helpviewer_keywords:
5+
helpviewer_keywords:
66
- "editors [Visual Studio SDK], legacy - adapters"
77
ms.assetid: a208d38e-9bea-41c9-9fe2-38bd86a359cb
88
author: "gregvanl"
99
ms.author: "gregvanl"
1010
manager: jillfra
11-
ms.workload:
11+
ms.workload:
1212
- "vssdk"
1313
---
1414
# Adapt legacy code to the editor
15-
The Visual Studio editor has many features that you can access from existing code components. The following instructions show how to adapt a non-MEF component, for example, a VSPackage, to consume editor functionality. The instructions also show how to use adapters to get the services of the editor in both managed and unmanaged code.
16-
17-
## Editor adapters
18-
Editor adapters, or shims, are wrappers for editor objects that also expose the classes and interfaces in the <xref:Microsoft.VisualStudio.TextManager.Interop> API. You can use the adapters to move between non-editor services for example, Visual Studio shell commands, and editor services. (This is how the editor is currently hosted in Visual Studio.) Adapters also enable legacy editor and language service extensions to work correctly in Visual Studio.
19-
20-
## Use editor adapters
21-
The <xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService> provides methods that switch between the new editor interfaces and the legacy interfaces, and also methods that create adapters.
22-
23-
If you are using this service in a MEF component part, you can import the service as follows.
24-
25-
```
26-
[Import(typeof(IVsEditorAdaptersFactoryService))]
27-
internal IVsEditorAdaptersFactoryService editorFactory;
28-
```
29-
30-
If you want to use this service in a non-MEF component, follow the instructions in the "Using Visual Studio Editor Services in a Non-MEF Component" section later in this topic.
31-
32-
## Switch between the new editor API and the legacy API
33-
Use the following methods to switch between an editor object and a legacy interface.
34-
35-
|Method|Conversion|
36-
|------------|----------------|
37-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetBufferAdapter%2A>|Converts an <xref:Microsoft.VisualStudio.Text.ITextBuffer> to an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer>.|
38-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetDataBuffer%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> to an <xref:Microsoft.VisualStudio.Text.ITextBuffer>.|
39-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetDocumentBuffer%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> to an <xref:Microsoft.VisualStudio.Text.ITextBuffer>.|
40-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetViewAdapter%2A>|Converts an <xref:Microsoft.VisualStudio.Text.Editor.ITextView> to an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView>.|
41-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetWpfTextView%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView> to an <xref:Microsoft.VisualStudio.Text.Editor.IWpfTextView>.|
42-
43-
## Create adapters
44-
Use the following methods to create adapters for legacy interfaces.
45-
46-
|Method|Conversion|
47-
|------------|----------------|
48-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsCodeWindowAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsCodeWindow>.|
49-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> for a specified <xref:Microsoft.VisualStudio.Utilities.IContentType>.|
50-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer>.|
51-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferCoordinatorAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBufferCoordinator>.|
52-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextViewAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView> for an <xref:Microsoft.VisualStudio.Text.Editor.ITextViewRoleSet>.|
53-
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextViewAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView>.|
54-
55-
## Creating adapters in unmanaged code
56-
All adapter classes are registered to be local co-creatable, and can be instantiated by using the `VsLocalCreateInstance()` function.
57-
58-
All adapters are created by using the GUIDs that are defined in the *vsshlids.h* file in the *\..\VisualStudioIntegration\Common\Inc\\* folder of the Visual Studio SDK installation. To create an instance of VsTextBufferAdapter, use the following code.
59-
60-
```
61-
IVsTextBuffer *pBuf = NULL;
62-
VsLocalCreateInstance(CLSID_VsTextBuffer, NULL, CLSCTX_INPROC_SERVER, IID_IVsTextBuffer, (void**)&pBuf);
63-
```
64-
65-
## Create adapters in managed code
66-
In managed code, you can co-create the adapters in the same way as that described for unmanaged code. You can also use a MEF service that lets you create and interact with adapters. This manner of getting an adapter enables more fine-grained control than you have when you co-create it.
67-
68-
### To create an adapter for IVsTextView
69-
70-
1. Add a reference to *Microsoft.VisualStudio.Editor.dll*. Make sure that `CopyLocal` is set to `false`.
71-
72-
2. Instantiate the <xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService>, as follows.
73-
74-
```
75-
using Microsoft.VisualStudio.Editor;
76-
...
77-
IVsEditorAdaptersFactoryService adapterFactoryService = ComponentModel.GetService<IVsEditorAdaptersFactoryService>();
78-
```
79-
80-
3. Call the `CreateX()` method.
81-
82-
```
83-
adapterFactoryService.CreateTextViewAdapter(textView);
84-
```
85-
86-
## Use the Visual Studio editor directly from unmanaged code
87-
The Microsoft.VisualStudio.Platform.VSEditor namespace and the Microsoft.VisualStudio.Platform.VSEditor.Interop namespace expose COM-callable interfaces as IVx* interfaces. For example, the Microsoft.VisualStudio.Platform.VSEditor.Interop.IVxTextBuffer interface is the COM version of the <xref:Microsoft.VisualStudio.Text.ITextBuffer> interface. From the `IVxTextBuffer`, you can get access to the buffer snapshots, modify the buffer, listen for text-change events on the buffer, and create tracking points and spans. The following steps show how to access an `IVxTextBuffer` from a `IVsTextBuffer`.
88-
89-
### To get an IVxTextBuffer
90-
91-
1. The definitions for the IVx\* interfaces are in the *VSEditor.h* file in the *\..\VisualStudioIntegration\Common\Inc\\* folder of the Visual Studio SDK installation.
92-
93-
2. The following code instantiates a text buffer by using the `IVsUserData->GetData()` method. In the following code, `pData` is a pointer to an `IVsUserData` object.
94-
95-
```cpp
96-
#include <textmgr.h>
97-
#include <VSEditor.h>
98-
#include <vsshlids.h>
99-
100-
CComPtr<IVsTextBuffer> pVsTextBuffer;
101-
CComPtr<IVsUserData> pData;
102-
CComPtr<IVxTextBuffer> pVxBuffer;
103-
...
104-
if (SUCCEEDED(pVsTextBuffer->QueryInterface(IID_IVsUserData, &pData))
105-
{
106-
CComVariant vt;
107-
if (SUCCEEDED(pData->GetData(GUID_VxTextBuffer, &vt)) &&
108-
(vt.Type == VT_UNKNOWN) && (vt.punkVal != NULL))
109-
{
110-
vt.punkVal->QueryInterface(IID_IVxTextBuffer, (void**)&pVxBuffer);
111-
}
112-
}
113-
```
114-
115-
## Use Visual Studio editor services in a non-MEF component
116-
If you have an existing managed code component that does not use MEF and you want to use the services of the Visual Studio editor, you must add a reference to the assembly that contains the ComponentModelHost VSPackage and get its SComponentModel service.
117-
118-
### To consume Visual Studio editor components from a non-MEF component
119-
120-
1. Add a reference to the *Microsoft.VisualStudio.ComponentModelHost.dll* assembly in the *\..\Common7\IDE\\* folder of the Visual Studio installation. Make sure that `CopyLocal` is set to `false`.
121-
122-
2. Add a private `IComponentModel` member to the class in which you want to use Visual Studio editor services, as follows.
123-
124-
```
125-
using Microsoft.VisualStudio.ComponentModelHost;
126-
....
127-
private IComponentModel componentModel;
128-
```
129-
130-
3. Instantiate the component model in the initialization method for your component.
131-
132-
```
133-
componentModel =
134-
(IComponentModel)Package.GetGlobalService(typeof(SComponentModel));
135-
```
136-
137-
4. After this, you can get any one of the Visual Studio editor services by calling the `IComponentModel.GetService<T>()` method for the service you want.
138-
139-
```
140-
textBufferFactoryService =
141-
componentModel.GetService<ITextBufferFactoryService>();
15+
The Visual Studio editor has many features that you can access from existing code components. The following instructions show how to adapt a non-MEF component, for example, a VSPackage, to consume editor functionality. The instructions also show how to use adapters to get the services of the editor in both managed and unmanaged code.
16+
17+
## Editor adapters
18+
Editor adapters, or shims, are wrappers for editor objects that also expose the classes and interfaces in the <xref:Microsoft.VisualStudio.TextManager.Interop> API. You can use the adapters to move between non-editor services for example, Visual Studio shell commands, and editor services. (This is how the editor is currently hosted in Visual Studio.) Adapters also enable legacy editor and language service extensions to work correctly in Visual Studio.
19+
20+
## Use editor adapters
21+
The <xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService> provides methods that switch between the new editor interfaces and the legacy interfaces, and also methods that create adapters.
22+
23+
If you are using this service in a MEF component part, you can import the service as follows.
24+
25+
```
26+
[Import(typeof(IVsEditorAdaptersFactoryService))]
27+
internal IVsEditorAdaptersFactoryService editorFactory;
28+
```
29+
30+
If you want to use this service in a non-MEF component, follow the instructions in the "Using Visual Studio Editor Services in a Non-MEF Component" section later in this topic.
31+
32+
## Switch between the new editor API and the legacy API
33+
Use the following methods to switch between an editor object and a legacy interface.
34+
35+
|Method|Conversion|
36+
|------------|----------------|
37+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetBufferAdapter%2A>|Converts an <xref:Microsoft.VisualStudio.Text.ITextBuffer> to an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer>.|
38+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetDataBuffer%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> to an <xref:Microsoft.VisualStudio.Text.ITextBuffer>.|
39+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetDocumentBuffer%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> to an <xref:Microsoft.VisualStudio.Text.ITextBuffer>.|
40+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetViewAdapter%2A>|Converts an <xref:Microsoft.VisualStudio.Text.Editor.ITextView> to an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView>.|
41+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.GetWpfTextView%2A>|Converts an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView> to an <xref:Microsoft.VisualStudio.Text.Editor.IWpfTextView>.|
42+
43+
## Create adapters
44+
Use the following methods to create adapters for legacy interfaces.
45+
46+
|Method|Conversion|
47+
|------------|----------------|
48+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsCodeWindowAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsCodeWindow>.|
49+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer> for a specified <xref:Microsoft.VisualStudio.Utilities.IContentType>.|
50+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBuffer>.|
51+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextBufferCoordinatorAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextBufferCoordinator>.|
52+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextViewAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView> for an <xref:Microsoft.VisualStudio.Text.Editor.ITextViewRoleSet>.|
53+
|<xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService.CreateVsTextViewAdapter%2A>|Creates an <xref:Microsoft.VisualStudio.TextManager.Interop.IVsTextView>.|
54+
55+
## Creating adapters in unmanaged code
56+
All adapter classes are registered to be local co-creatable, and can be instantiated by using the `VsLocalCreateInstance()` function.
57+
58+
All adapters are created by using the GUIDs that are defined in the *vsshlids.h* file in the *\..\VisualStudioIntegration\Common\Inc\\* folder of the Visual Studio SDK installation. To create an instance of VsTextBufferAdapter, use the following code.
59+
60+
```
61+
IVsTextBuffer *pBuf = NULL;
62+
VsLocalCreateInstance(CLSID_VsTextBuffer, NULL, CLSCTX_INPROC_SERVER, IID_IVsTextBuffer, (void**)&pBuf);
63+
```
64+
65+
## Create adapters in managed code
66+
In managed code, you can co-create the adapters in the same way as that described for unmanaged code. You can also use a MEF service that lets you create and interact with adapters. This manner of getting an adapter enables more fine-grained control than you have when you co-create it.
67+
68+
### To create an adapter for IVsTextView
69+
70+
1. Add a reference to *Microsoft.VisualStudio.Editor.dll*. Make sure that `CopyLocal` is set to `false`.
71+
72+
2. Instantiate the <xref:Microsoft.VisualStudio.Editor.IVsEditorAdaptersFactoryService>, as follows.
73+
74+
```
75+
using Microsoft.VisualStudio.Editor;
76+
...
77+
IVsEditorAdaptersFactoryService adapterFactoryService = ComponentModel.GetService<IVsEditorAdaptersFactoryService>();
78+
```
79+
80+
3. Call the `CreateX()` method.
81+
82+
```
83+
adapterFactoryService.CreateTextViewAdapter(textView);
84+
```
85+
86+
## Use the Visual Studio editor directly from unmanaged code
87+
The Microsoft.VisualStudio.Platform.VSEditor namespace and the Microsoft.VisualStudio.Platform.VSEditor.Interop namespace expose COM-callable interfaces as IVx* interfaces. For example, the Microsoft.VisualStudio.Platform.VSEditor.Interop.IVxTextBuffer interface is the COM version of the <xref:Microsoft.VisualStudio.Text.ITextBuffer> interface. From the `IVxTextBuffer`, you can get access to the buffer snapshots, modify the buffer, listen for text-change events on the buffer, and create tracking points and spans. The following steps show how to access an `IVxTextBuffer` from a `IVsTextBuffer`.
88+
89+
### To get an IVxTextBuffer
90+
91+
1. The definitions for the IVx\* interfaces are in the *VSEditor.h* file in the *\..\VisualStudioIntegration\Common\Inc\\* folder of the Visual Studio SDK installation.
92+
93+
2. The following code instantiates a text buffer by using the `IVsUserData->GetData()` method. In the following code, `pData` is a pointer to an `IVsUserData` object.
94+
95+
```cpp
96+
#include <textmgr.h>
97+
#include <VSEditor.h>
98+
#include <vsshlids.h>
99+
100+
CComPtr<IVsTextBuffer> pVsTextBuffer;
101+
CComPtr<IVsUserData> pData;
102+
CComPtr<IVxTextBuffer> pVxBuffer;
103+
...
104+
if (SUCCEEDED(pVsTextBuffer->QueryInterface(IID_IVsUserData, &pData))
105+
{
106+
CComVariant vt;
107+
if (SUCCEEDED(pData->GetData(GUID_VxTextBuffer, &vt)) &&
108+
(vt.Type == VT_UNKNOWN) && (vt.punkVal != NULL))
109+
{
110+
vt.punkVal->QueryInterface(IID_IVxTextBuffer, (void**)&pVxBuffer);
111+
}
112+
}
113+
```
114+
115+
## Use Visual Studio editor services in a non-MEF component
116+
If you have an existing managed code component that does not use MEF and you want to use the services of the Visual Studio editor, you must add a reference to the assembly that contains the ComponentModelHost VSPackage and get its SComponentModel service.
117+
118+
### To consume Visual Studio editor components from a non-MEF component
119+
120+
1. Add a reference to the *Microsoft.VisualStudio.ComponentModelHost.dll* assembly in the *\..\Common7\IDE\\* folder of the Visual Studio installation. Make sure that `CopyLocal` is set to `false`.
121+
122+
2. Add a private `IComponentModel` member to the class in which you want to use Visual Studio editor services, as follows.
123+
124+
```
125+
using Microsoft.VisualStudio.ComponentModelHost;
126+
....
127+
private IComponentModel componentModel;
128+
```
129+
130+
3. Instantiate the component model in the initialization method for your component.
131+
132+
```
133+
componentModel =
134+
(IComponentModel)Package.GetGlobalService(typeof(SComponentModel));
135+
```
136+
137+
4. After this, you can get any one of the Visual Studio editor services by calling the `IComponentModel.GetService<T>()` method for the service you want.
138+
139+
```
140+
textBufferFactoryService =
141+
componentModel.GetService<ITextBufferFactoryService>();
142142
```

0 commit comments

Comments
 (0)