Share via

IVsHierarchyRefactorNotify Interface

  • Article

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

'Usage
Dim instance As IVsHierarchyRefactorNotify

[InterfaceTypeAttribute()]
[GuidAttribute("FE5FEE31-C302-4961-876F-F3C8F853E4F8")]
public interface IVsHierarchyRefactorNotify

[InterfaceTypeAttribute()]
[GuidAttribute(L"FE5FEE31-C302-4961-876F-F3C8F853E4F8")]
public interface class IVsHierarchyRefactorNotify

public interface IVsHierarchyRefactorNotify

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

  1. The user invokes symbolic renaming or any other refactoring operation.

  2. The Visual Studio language service determines which code files the operation affects.

  3. The language service calls IVsHierarchyRefactorNotify.OnBefore methods to notify the hierarchy which files are affected by this operation.

  4. The hierarchy determines if any affected files are generated from the designer files.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. After checkout, the hierarchy returns from the IVsHierarchyRefactorNotify.OnBefore call to the language service.

  10. The language service carries out the refactoring operation.

  11. 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

IVsHierarchyRefactorNotify Members

Microsoft.VisualStudio.Shell.Interop Namespace

Other Resources

Refactoring