IVsHierarchyRefactorNotify Interface

Reference

Definition

Namespace:: Microsoft.VisualStudio.Shell.Interop

Assembly:: Microsoft.VisualStudio.Shell.Interop.8.0.dll

Assembly:: Microsoft.VisualStudio.Interop.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Notifies the hierarchy of refactoring operations.

public interface class IVsHierarchyRefactorNotify

public interface class IVsHierarchyRefactorNotify

__interface IVsHierarchyRefactorNotify

[System.Runtime.InteropServices.Guid("FE5FEE31-C302-4961-876F-F3C8F853E4F8")]
[System.Runtime.InteropServices.InterfaceType(1)]
public interface IVsHierarchyRefactorNotify

[<System.Runtime.InteropServices.Guid("FE5FEE31-C302-4961-876F-F3C8F853E4F8")>]
[<System.Runtime.InteropServices.InterfaceType(1)>]
type IVsHierarchyRefactorNotify = interface

Public Interface IVsHierarchyRefactorNotify

Attributes: GuidAttribute InterfaceTypeAttribute

Remarks

To support refactoring operations, your project system must implement the IVsHierarchy, which represents a hierarchy, IVsProject, and IVsHierarchyRefactorNotify interfaces. You also must implement a language service to provide support for the features associated with editing of the source code including the refactoring operations. For more information about the language service, see Legacy Language Service Interfaces.

By implementing IVsHierarchyRefactorNotify, you provide your language service with the capability to notify the IVsHierarchy interface about refactoring operations, such as symbolic renaming or parameter reordering. If the hierarchy uses build providers, single file generators or some other services to generate code, it must obtain a reference to the object that implements the IVsRefactorNotify interface.

Each project system and a language service define a specific way of obtaining a reference to the IVsRefactorNotify object. For example, the Visual Basic, Visual C#, or Visual J# desktop project systems obtain a reference to the object that implements IVsRefactorNotify by calling IUnknown::QueryInterface on the object that implements IVsSingleFileGenerator. The Visual Basic, Visual C#, or Visual J# Web project systems call QueryService by using a Guid registered under the HKLM\Software\Microsoft\VisualStudio\8.0\Projects\{project-system-guid}\FileExtensions\{file extension}\RefactorNotify registry key. The hierarchy passes the notification to the IVsRefactorNotify object to incorporate the refactoring operation into the designer file or to stop the operation and return an error message via IErrorInfo. The designer file can be any of the input files provided by Visual Studio, such as .resx, .xsd, .settings, .map and .myapp files or any other file extension associated with a code generator or build provider.

To successfully complete the full refactoring operation, the hierarchy must check out the files passed to the IVsHierarchyRefactorNotify and the files returned from corresponding IVsRefactorNotify method calls.

The hierarchy must display an error message in the message box when the refactoring operation fails.

Flow of Operation

The user invokes symbolic renaming or any other refactoring operation.
The Visual Studio language service determines which code files the operation affects.
The language service calls IVsHierarchyRefactorNotify.OnBefore methods to notify the hierarchy which files are affected by this operation.
The hierarchy determines if any affected files are generated from the designer files.
If files are generated, the hierarchy obtains a reference to the object that implements IVsRefactorNotify and sends the IVsRefactorNotify.OnBefore notifications to the IVsRefactorNotify implementer for each generated file.
The IVsRefactorNotify implementer can stop the operation by returning a failure and setting an error by calling the M:Microsoft.VisualStudio.Shell.Interop.IVsUIShell.SetErrorInfo(System.Int32,System.String,System.UInt32,System.String,System.String) method. If the IVsRefactorNotify implementer does not want to stop the operation, it determines which designer files the operation affects and returns the set of files to IVsHierarchyRefactorNotify in the out array, VSITEMID.

Note

The IVsRefactorNotify implementer must not update the designer files at this point. The files must be updated during the second call to the IVsRefactorNotify.On methods, for example, during the OnGlobalSymbolRenamed method call. The IVsRefactorNotify.OnBefore method calls enable the hierarchy to check out the generated files as a unit. The hierarchy has the option to stop the entire operation before any changes are made, if one of the code generators cannot consume the refactor operation.
If the IVsRefactorNotify implementer returns a failure, the hierarchy must alert the user about the error. The hierarchy can continue the operation or cancel and stoop the refactor operation. If the operation is stopped, the HRESULT contains the following values:

E_ABORT

OLE_E_PROMPTSAVECANCELLED

OLECMDERR_E_CANCELED

HR_E_CSHARP_USER_CANCEL.
If the IVsRefactorNotify implementer returns successfully or the caller requests to continue on failure, the hierarchy must check out the files passed to IVsHierarchyRefactorNotify and files returned from corresponding IVsRefactorNotify methods calls.

Note

Some refactor operations do not cause changes in the designer file and, therefore, the designer file is not automatically checked out. The IVsRefactorNotify implementer must request a check out of the designer file, if the content is changed by the identified refactoring operation. This is accomplished by returning the VSITEMID that identifies the designer file in the out array. An example of a scenario where a designer file does not need to be checked out is when a namespace, which is stored outside the designer file, changes. The designer file does not need to be checked out even though the generated code file has changed.
After checkout, the hierarchy returns from the IVsHierarchyRefactorNotify.OnBefore call to the language service.
The language service carries out the refactoring operation.
The language service notifies the hierarchy about the completion of the refactoring operation by calling the IVsHierarchyRefactorNotify.On methods, such as OnGlobalSymbolRenamed, and the hierarchy notifies all IVsRefactorNotify implementers by calling the IVsRefactorNotify.On methods, such as OnGlobalSymbolRenamed. The equivalent refactoring change is made in the designer files. This assures that the refactoring operation remains preserved.

Methods

OnAddParams(UInt32, String, UInt32, UInt32[], String[], String[])	Called after a method had parameters added.
OnBeforeAddParams(UInt32, String, UInt32, UInt32[], String[], String[], Int32)	Called when a method is about to have parameters added.
OnBeforeGlobalSymbolRenamed(UInt32, UInt32[], UInt32, String[], String, Int32)	Called when a symbol is about to be renamed.
OnBeforeRemoveParams(UInt32, String, UInt32, UInt32[], Int32)	Called when a method is about to have parameters removed.
OnBeforeReorderParams(UInt32, String, UInt32, UInt32[], Int32)	Called when a method is about to have parameters reordered.
OnGlobalSymbolRenamed(UInt32, UInt32[], UInt32, String[], String)	Called after a symbol is renamed.
OnRemoveParams(UInt32, String, UInt32, UInt32[])	Called after a method had parameters removed.
OnReorderParams(UInt32, String, UInt32, UInt32[])	Called after a method had parameters reordered.

Applies to