Merge pull request #4469 from gewarren/extensibility-0417

Random extensibility fixes

Author: v-dansch

docs/extensibility/creating-custom-editors-and-designers.md

@@ -13,6 +13,7 @@ ms.workload:
   - "vssdk"
 ---
 # Create custom editors and designers
+
 The Visual Studio integrated development environment (IDE) can host different types of editor:
 
 - The Visual Studio core editor
@@ -23,10 +24,11 @@ The Visual Studio integrated development environment (IDE) can host different ty
 
 - Designers
 
-  The following information helps you choose the type of editor you need.
+The following information helps you choose the type of editor you need.
 
 ## Types of editor
- For information about the Visual Studio core editor, see [Extend the editor and language services](../extensibility/extending-the-editor-and-language-services.md).
+
+For information about the Visual Studio core editor, see [Extend the editor and language services](../extensibility/extending-the-editor-and-language-services.md).
 
 ### Custom editors
  A custom editor is one that is designed to work in specialized circumstances. For example, you might create an editor whose function is to read and write data to a specific repository, such as a Microsoft Exchange server. Choose a custom editor if you want an editor that works with your project type only or if you want an editor that has only a few specific commands. Note, however, that users will not be able to use a custom editor to edit standard [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] projects.
@@ -64,33 +66,36 @@ The Visual Studio integrated development environment (IDE) can host different ty
    If it can be embedded, you should create a host window for the external editor and then call the <xref:Microsoft.VisualStudio.Shell.Interop.IVsProject3.IsDocumentInProject%2A> method and set the <xref:Microsoft.VisualStudio.Shell.Interop.VSDOCUMENTPRIORITY> enumeration value to `DP_External`. If the editor cannot be embedded, the IDE will automatically create a separate window for it.
 
 ## In This Section
-- [Walkthrough: Create a custom editor](../extensibility/walkthrough-creating-a-custom-editor.md)
- Explains how to create a custom editor.
 
-- [Walkthrough: Add features to a custom editor](../extensibility/walkthrough-adding-features-to-a-custom-editor.md)
- Explains how to add features to a custom editor.
+[Walkthrough: Create a custom editor](../extensibility/walkthrough-creating-a-custom-editor.md)\
+Explains how to create a custom editor.
+
+[Walkthrough: Add features to a custom editor](../extensibility/walkthrough-adding-features-to-a-custom-editor.md)\
+Explains how to add features to a custom editor.
 
-- [Designer initialization and metadata configuration](../extensibility/designer-initialization-and-metadata-configuration.md)
- Explains how to initialize a designer.
+[Designer initialization and metadata configuration](../extensibility/designer-initialization-and-metadata-configuration.md)\
+Explains how to initialize a designer.
 
-- [Supply undo support to designers](../extensibility/supplying-undo-support-to-designers.md)
- Explains how to provide undo support for designers.
+[Supply undo support to designers](../extensibility/supplying-undo-support-to-designers.md)\
+Explains how to provide undo support for designers.
 
-- [Syntax coloring in custom editors](../extensibility/syntax-coloring-in-custom-editors.md)
- Explains the difference between syntax coloring in the core editor and in custom editors.
+[Syntax coloring in custom editors](../extensibility/syntax-coloring-in-custom-editors.md)\
+Explains the difference between syntax coloring in the core editor and in custom editors.
 
-- [Document data and document view in custom editors](../extensibility/document-data-and-document-view-in-custom-editors.md)
- Explains how to implement document data and document views in custom editors.
+[Document data and document view in custom editors](../extensibility/document-data-and-document-view-in-custom-editors.md)\
+Explains how to implement document data and document views in custom editors.
 
 ## Related sections
-- [Legacy interfaces in the editor](../extensibility/legacy-interfaces-in-the-editor.md)
- Explains how to access the core editor by means of the legacy API.
 
-- [Develop a legacy language service](../extensibility/internals/developing-a-legacy-language-service.md)
- Explains how to implement a language service.
+[Legacy interfaces in the editor](../extensibility/legacy-interfaces-in-the-editor.md)\
+Explains how to access the core editor by means of the legacy API.
 
-- [Extend other parts of Visual Studio](../extensibility/extending-other-parts-of-visual-studio.md)
- Explains how to create UI elements that match the rest of [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)].
+[Develop a legacy language service](../extensibility/internals/developing-a-legacy-language-service.md)\
+Explains how to implement a language service.
+
+[Extend other parts of Visual Studio](../extensibility/extending-other-parts-of-visual-studio.md)\
+Explains how to create UI elements that match the rest of [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)].
 
 ## See also
+
 - <xref:Microsoft.VisualStudio.Shell.Interop.IVsEditorFactory>

docs/extensibility/designer-initialization-and-metadata-configuration.md

@@ -13,81 +13,86 @@ ms.workload:
   - "vssdk"
 ---
 # Designer initialization and metadata configuration
+
 Manipulation of the metadata and filter attributes associated with a designer or designer component provides a mechanism for applications to define which tools are used by a particular designer to handle different <xref:System.Type> objects (such as data structures, classes, or graphical entities), when the designer is available, and how the Visual Studio IDE is configured to support the designer (for instance which **Toolbox** category or tab is available).
 
- The [!INCLUDE[vsipsdk](../extensibility/includes/vsipsdk_md.md)] provides several mechanisms to facilitate the control of a designer's or designer component's initialization and the manipulation of its metadata by a VSPackage.
+The [!INCLUDE[vsipsdk](../extensibility/includes/vsipsdk_md.md)] provides several mechanisms to facilitate the control of a designer's or designer component's initialization and the manipulation of its metadata by a VSPackage.
 
 ## Initialize metadata and configuration information
- Because they are loaded on demand, VSPackages may not have been loaded by the [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] environment prior to the instantiation of a designer. Therefore, VSPackages cannot use the standard mechanism for configuring a designer or designer component on creation, which is to handle a <xref:System.ComponentModel.Design.IDesignerEventService.DesignerCreated> event. Instead, a VSPackage implements an instance of the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> interface and  registers itself to provide customizations, referred to as design surface extensions.
+ Because they are loaded on demand, VSPackages may not have been loaded by the Visual Studio environment prior to the instantiation of a designer. Therefore, VSPackages cannot use the standard mechanism for configuring a designer or designer component on creation, which is to handle a <xref:System.ComponentModel.Design.IDesignerEventService.DesignerCreated> event. Instead, a VSPackage implements an instance of the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> interface and  registers itself to provide customizations, referred to as design surface extensions.
 
 ### Customize initialization
- Customizing a designer, a component, or a designer surface, involves:
+
+Customizing a designer, a component, or a designer surface, involves:
 
 1. Modifying the designer metadata and effectively changing how a certain <xref:System.Type> is accessed or converted.
 
     This is typically done through the <xref:System.Drawing.Design.UITypeEditor> or <xref:System.ComponentModel.TypeConverter> mechanisms.
 
-    For example, when <xref:System.Windows.Forms>-based designers are initialized, the [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] environment modifies the <xref:System.Drawing.Design.UITypeEditor> for <xref:System.Web.UI.WebControls.Image> objects used with the designer to use the resource manager to obtain bitmaps rather than the file system.
+    For example, when <xref:System.Windows.Forms>-based designers are initialized, the Visual Studio environment modifies the <xref:System.Drawing.Design.UITypeEditor> for <xref:System.Web.UI.WebControls.Image> objects used with the designer to use the resource manager to obtain bitmaps rather than the file system.
 
 2. Integrating with the environment, for example, by subscribing to events or obtaining project configuration information. You can obtain project configuration information and subscribe to events by obtaining the <xref:System.ComponentModel.Design.ITypeResolutionService> interface.
 
 3. Modification of the user environment by activating appropriate **Toolbox** categories or by restricting the designer's applicability by applying an instance of the <xref:System.ComponentModel.ToolboxItemFilterAttribute> class to the designer.
 
 ### Designer initialization by a VSPackage
- A VSPackage should handle designer initialization by:
+
+A VSPackage should handle designer initialization by:
 
 1. Creating an object implementing the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> class.
 
    > [!NOTE]
-   >  The <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> class should never be implemented on the same object as the <xref:Microsoft.VisualStudio.Shell.Package> class.
+   > The <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> class should never be implemented on the same object as the <xref:Microsoft.VisualStudio.Shell.Package> class.
 
-2. Register the class implementing <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> as providing support for the VSPackage's designer extensions by applying instances of  <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtensionAttribute>, <xref:Microsoft.VisualStudio.Shell.ProvideObjectAttribute> and <xref:Microsoft.VisualStudio.Shell.ProvideServiceAttribute> to the class providing the VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package>.
+2. Registering the class that implements <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> as providing support for the VSPackage's designer extensions. Register the class by applying instances of  <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtensionAttribute>, <xref:Microsoft.VisualStudio.Shell.ProvideObjectAttribute>, and <xref:Microsoft.VisualStudio.Shell.ProvideServiceAttribute> to the class that provides the VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package>.
 
-   Whenever any designer or designer component is created, the [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] environment:
+Whenever a designer or designer component is created, the Visual Studio environment:
 
-3. Accesses each registered design surface extension provider.
+- Accesses each registered design surface extension provider.
 
-4. Instantiates and initializes an instance of each design surface extension provider's <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object
+- Instantiates and initializes an instance of each design surface extension provider's <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object.
 
-5. Calls each design surface extension provider's <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension.OnDesignerCreated%2A> method or <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension.OnComponentCreated%2A> method (as appropriate).
+- Calls each design surface extension provider's <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension.OnDesignerCreated%2A> method or <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension.OnComponentCreated%2A> method (as appropriate).
 
-   When implementing the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object as a member of a VSPackage, it is important to understand that:
+When implementing the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object as a member of a VSPackage, it is important to understand that:
 
-6. The [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] environment does not provide any control over what metadata or other configuration settings a particular `DesignSurfaceExtension` provider's modifies. It is possible for two or more `DesignSurfaceExtension` providers modifying the same designer feature in conflicting ways, with the final modification being definitive. It is indeterminate which modification is last applied.
+- The Visual Studio environment does not provide any control over what metadata or other configuration settings a particular `DesignSurfaceExtension` provider's modifies. It is possible for two or more `DesignSurfaceExtension` providers modifying the same designer feature in conflicting ways, with the final modification being definitive. It is indeterminate which modification is last applied.
 
-7. It is possible to explicitly restrict an implementation of the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object to specific designers, by applying instances of <xref:System.ComponentModel.ToolboxItemFilterAttribute> to that implementation. For more information on **Toolbox** item filtering, see the <xref:System.ComponentModel.ToolboxItemFilterAttribute> and <xref:System.ComponentModel.ToolboxItemFilterType>.
+- It's possible to explicitly restrict an implementation of the <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension> object to specific designers by applying instances of <xref:System.ComponentModel.ToolboxItemFilterAttribute> to that implementation. For more information on **Toolbox** item filtering, see the <xref:System.ComponentModel.ToolboxItemFilterAttribute> and <xref:System.ComponentModel.ToolboxItemFilterType>.
 
 ## Additional metadata provisioning
- A VSPackage can change the configuration of a designer or designer component other than at design time.
 
- The <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> class can be used programmatically, or be applied to a VSPackage providing a designer.
+A VSPackage can change the configuration of a designer or designer component other than at design time.
 
- An instance of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> class is used to modify the metadata of components created on a design surface. For example, one could replace a default property browser used by <xref:System.Windows.Forms.CommonDialog> objects, with a custom property browser.
+The <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> class can be used programmatically or applied to a VSPackage that provides a designer.
 
- Modifications provided by an instance of <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> applied to a VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package> can have one of two scopes:
+An instance of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> class is used to modify the metadata of components created on a design surface. For example, one could replace a default property browser used by <xref:System.Windows.Forms.CommonDialog> objects with a custom property browser.
+
+Modifications provided by an instance of <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> applied to a VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package> can have one of two scopes:
 
 - Global -- for all new instances of a given component
 
 - Local -- pertaining only to instance of the component created on a design surface provided by the current VSPackage.
 
-  The `IsGlobal` property of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> instance applied to a VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package> determines this scope.
+The `IsGlobal` property of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> instance applied to a VSPackage's implementation of <xref:Microsoft.VisualStudio.Shell.Package> determines this scope.
 
-  Applying the attribute to an implementation of <xref:Microsoft.VisualStudio.Shell.Package> with the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute.IsGlobal%2A> property of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> object set to `true`, as below, changes the browser for the entire [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] environment:
+Applying the attribute to an implementation of <xref:Microsoft.VisualStudio.Shell.Package> with the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute.IsGlobal%2A> property of the <xref:Microsoft.VisualStudio.Shell.Design.ProvideDesignerMetadataAttribute> object set to `true`, as below, changes the browser for the entire Visual Studio environment:
 
-  `[ProvideDesignerMetadata(typeof(Color), typeof(CustomBrowser),`   `IsGlobal=true`  `)]`
+`[ProvideDesignerMetadata(typeof(Color), typeof(CustomBrowser),`   `IsGlobal=true`  `)]`
 
-  `internal class MyPackage : Package {}`
+`internal class MyPackage : Package {}`
 
-  If the global flag was set to `false`, then the metadata change is local to the current designer supported by the current VSPackage:
+If the global flag was set to `false`, then the metadata change is local to the current designer supported by the current VSPackage:
 
-  `[ProvideDesignerMetadata(typeof(Color), typeof(CustomBrowser),`   `IsGlobal=false`  `)]`
+`[ProvideDesignerMetadata(typeof(Color), typeof(CustomBrowser),`   `IsGlobal=false`  `)]`
 
-  `internal class MyPackage : Package {}`
+`internal class MyPackage : Package {}`
 
 > [!NOTE]
->  At the present time, the design surface only supports creating components, and therefore only components can have local metadata. In the example above, we were attempting to modify a property, such as the `Color` property of an object. If `false` was passed in for the global flag, `CustomBrowser` would never appear because the designer never actually creates an instance of `Color`. Setting the global flag to `false` is useful for components, such as controls, timers, and dialog boxes.
+> The design surface only supports creating components, and therefore only components can have local metadata. In the example above, we were attempting to modify a property, such as the `Color` property of an object. If `false` was passed in for the global flag, `CustomBrowser` would never appear because the designer never actually creates an instance of `Color`. Setting the global flag to `false` is useful for components, such as controls, timers, and dialog boxes.
 
 ## See also
+
 - <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtension>
 - <xref:Microsoft.VisualStudio.Shell.Design.DesignSurfaceExtensionAttribute>
 - <xref:System.ComponentModel.ToolboxItemFilterType>