How to: Add a Custom Editor and a Custom Result Viewer

You can add a custom editor that provides specific user interface functionality to your test type. You can also add a custom result viewer that is designed specifically to display the test results of your test type. To add one or both, do the following:

• Provide the custom UI that can be launched from Visual Studio.

• Advertise the custom editor and result viewer so that the framework knows to associate these new UI components with the new test type.

To add a custom editor and a custom viewer, you must implement a VSIP package. For detailed information, see the VSIP documentation.

The steps for creating a custom editor and a custom viewer are as follows:

1. Define the UI of the custom editor

2. Define the UI for the custom results viewer

3. Implement ITuip for advertising the new editor and viewer

Define the UI of the Custom Editor

To define the UI for the custom editor

• To provide a custom editor for your test type, you must subclass EditorFactory and TuipEditorControl. By implementing EditorFactory, you are providing a standard VSIP editor factory to Visual Studio.

  Providing a standard VSIP editor factory means that you can access your editor two different ways: when you open your test from one of the Test windows and when you double-click to open a file from Solution Explorer. This occurs when your test is stored in a file and the file name extension is recognized by Visual Studio.

  When you open your test or the file that contains it, EditorFactory interacts with Visual Studio to create a document window. The document window, in turn, hosts your TuipEditorControl. Your TuipEditorControl is where you actually define the UI by using Window Forms.

  注意

  Using EditorFactory and TuipEditorControl is a simple and quick way to implement a custom editor. However, you might have reason to implement your custom editor by implementing the VSIP "IVsEditorFactory" interface instead.

  For example, you might not want to host your custom-editor UI within Visual Studio. You might prefer that a different application, outside of Visual Studio, opens instead, such as when a test user double-clicks a file that contains your test.

  EditorFactory:

  protected abstract string EditorCaption { get; }

  Returns the caption that will appear in the editor window title. For example, if the file being edited is called MyFile and the caption is "MyEditor," the editor window title would read "MyFile [MyEditor]"

  protected abstract WindowPane CreateEditor(string monikerDocument);

  This creates and returns the custom editor window. In the custom editor window, create a new instance of your editor control, which is subclassed from TuipEditorControl. Then, wrap the control in a new instance of TuipEditorWindowPane and return it.

  The monikerDocument parameter can be ignored, because the loading of data occurs elsewhere.

  Your implementation of this method might look something like this:

  // Load the control

  TuipEditorControl editorForm = new MyTestEditorControl(base.VSServiceProvider);

  // Wrap it in a window pane

  TuipEditorWindowPane pane = new TuipEditorWindowPane(typeof(MyTestEditorFactory).GUID, editorForm, base.VSServiceProvider);

  return pane;

  protected abstract Guid GuidCmdUI { get; }

  This returns the Command UI GUID. This GUID is active when this editor is activated. Any UI element that is visible in the editor must use this GUID. This GUID is used in the .ctc file in the satellite DLL, where it indicates which menus and toolbars should be displayed when the document is active. You can return Guid.Empty if you do not need this functionality.

TuipEditorControl:

Define the UI for the Custom Results Viewer

To define the UI for the custom results viewer

• To provide the UI for your custom results viewer, you have to implement a tool window. To implement a tool window, you can subclass ToolWindowPane, which is a class provided as part of the managed VSIP framework. For detailed information about ToolWindowPane, see the VSIP documentation.

  In your results viewer, you have the option to host a control named “DetailedResultsControl.” Given a test result, the DetailedResultsControl can display the test name, result outcome, time taken to run the results, name of the computer, start time, and end time. If you use this control, you will likely want to divide your UI into two parts. In one part, the header should show the DetailedResultsControl. The other part should show your custom UI control.

  Using the DetailedResultsControl is simple. When the tool window loads a result, create a new instance of the control, if it is not already created, and then call its Init method:

  public void Init(TestResult result, IServiceProvider vsServiceProvider, IServiceProvider menuServiceProvider, Control customControl);

  Pass the test result and your custom UI control to this method. The DetailedResultsControl must know about your custom UI control because it has an expand/collapse feature that affects the size and positioning of your custom UI control.

Implement ITuip for Advertising the New Editor and Viewer

ITuip is the interface that tells the system which user-interface services are available for a custom test type and which extensibility areas the custom test type supports.

To implement ITuip

• To extend the actual UI, subclass the BaseTuip class. This class implements ITuip. You can also implement ITuip directly.

  Your class should also implement a new Visual Studio service that you define. Your package should handle both adding the service to Visual Studio and creating the service. The service provides an entry point for the framework to instantiate your TUIP implementation. For more information about Visual Studio services, see the VSIP documentation.

  BaseTuip:

  public virtual void InvokeEditor(UIBlob uiBlob, ITestElement test);

  BaseTuip’s implementation of InvokeEditor calls Visual Studio to open the editor for the test element. Provided you have implemented and registered an editor factory for your test, Visual Studio will invoke your editor.

  You do not have to override this method, although you could override it to add behavior, such as performing validation or displaying a message box.

  public abstract void InvokeResultViewer(TestResultMessage result);

  Implement this method to show the results viewer tool window of your test type, and load the result into the viewer.

  public abstract void CloseResultViewer(TestResultMessage result);

  Implement this method to close the results viewer tool window. The framework calls this method when the result is to be unloaded, for example, when the Visual Studio solution is to be closed.

  public abstract IRunConfigurationCustomEditor RunConfigurationEditor { get; }

  Implement this method to provide a page in the run configuration dialog box for your test type. Return null if you do not want to provide such a page.

  public virtual void UpdateTestProperty(ITestElement test, System.ComponentModel.PropertyDescriptor property)

  BaseTuip’s implementation of UpdateTestProperty updates and saves the test with the changes as described in the PropertyDescriptor. Or, if the test is currently opened in the editor, the changes will not be committed immediately but the editor will reflect those changes instead. This method is called by the framework when, for example, the user changes the property of a test using the properties grid. You do not have to override this method.

  public virtual void UpdateTestCustomProperty(ITestElement test, string property)

  Similar to UpdateTestProperty, BaseTuip’s implementation of UpdateTestCustomProperty updates and saves the test which has the value of a custom property changed. You do not have to override this method.

  public virtual bool IsTestPropertiesReadOnly(ITestElement test)

  BaseTuip’s implementation of this method returns False. False means that the set of properties for the test should not be read only; that is, users can modify the set of properties by using the Properties Grid. You can override this method to return True if you do not want users to be able to modify this test by using the Properties Grid.

See Also

Concepts

Implementing Custom Test Types