IVsHierarchyRefactorNotify Interface
Notifies the hierarchy of refactoring operations.
Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)
Syntax
'Declaration
<InterfaceTypeAttribute()> _
<GuidAttribute("FE5FEE31-C302-4961-876F-F3C8F853E4F8")> _
Public Interface IVsHierarchyRefactorNotify
[InterfaceTypeAttribute()]
[GuidAttribute("FE5FEE31-C302-4961-876F-F3C8F853E4F8")]
public interface IVsHierarchyRefactorNotify
[InterfaceTypeAttribute()]
[GuidAttribute(L"FE5FEE31-C302-4961-876F-F3C8F853E4F8")]
public interface class IVsHierarchyRefactorNotify
[<InterfaceTypeAttribute()>]
[<GuidAttribute("FE5FEE31-C302-4961-876F-F3C8F853E4F8")>]
type IVsHierarchyRefactorNotify = interface end
public interface IVsHierarchyRefactorNotify
The IVsHierarchyRefactorNotify type exposes the following members.
Methods
| Name | Description | |
|---|---|---|
.gif "Public method") |
OnAddParams | Called after a method had parameters added. |
|
OnBeforeAddParams | Called when a method is about to have parameters added. |
|
OnBeforeGlobalSymbolRenamed | Called when a symbol is about to be renamed. |
|
OnBeforeRemoveParams | Called when a method is about to have parameters removed. |
|
OnBeforeReorderParams | Called when a method is about to have parameters reordered. |
|
OnGlobalSymbolRenamed | Called after a symbol is renamed. |
|
OnRemoveParams | Called after a method had parameters removed. |
|
OnReorderParams | Called after a method had parameters reordered. |
Top
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 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.
See Also
Reference
Microsoft.VisualStudio.Shell.Interop Namespace