Visual Basic 2005: A Developer's Notebook

Rename All Instances of Any Program Element

Symbolic rename allows you to rename all instances of any element you declare in your program, from classes and interfaces to properties and methods, in a single step. This technique, which is decidedly not a simple text search-and-replace feature by virtue of its awareness of program syntax, solves many knotty problems found in previous releases of Visual Basic. For example, imagine you want to rename a public property named FirstName. If you use search-and-replace, you'll also inadvertently affect a text box named txtFirstName, an event handler named cmdFirstName_Click, a database field accessed through row("FirstName"), and even your code comments. With symbolic rename, the IDE takes care of renaming just what you want, and it completes all of its work in a single step.

Note

Need to rename a method, property, or variable without mangling other similar names in the same file? Visual Studio 2005 includes the perfect antidote to clumsy search-and-replace.

How do I do that?

You can use symbolic rename from any code window. To understand how it works, create a form that has a single text box named TextBox1 and a button named cmdText. Finally, add the form code in Example 1-2.

Example 1-2. A simple form that uses the word "Text" heavily

Public Class TextTest
    
    Private Sub TextTest_Load(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles MyBase.Load
        ' Get the text from the text box.
        Dim Text As String = TextBox1.Text
    
        ' Convert and display the text.
        Text = ConvertText(Text)
        MessageBox.Show("Uppercase Text is: " & Text)
    End Sub
    
    Public Function ConvertText(ByVal Text As String) As String
        Return Text.ToUpper( )
    End Function
    
End Class

This code performs a relatively mundane task: converting a user-supplied string to uppercase and displays it in a message box. What's notable is how many places it uses the word "Text." Now, consider what happens if you need to rename the local variable Text in the event handler for the Form.Load event. Clearly, this is enough to confuse any search-and-replace algorithm. That's where symbolic rename comes in.

To use symbolic rename, simply right-click on the local Text variable, and select Rename from the context menu. In the Rename dialog box, enter the new variable name LocalText and click OK. All the appropriate instances in your code will be changed automatically without affecting other elements in your code (such as the text box, the comments, the literal text string, the form class name, the Text parameter in the ConvertText function, and so on). Here's the resulting code:

Public Class TextTest
    
    Private Sub cmdTest_Click(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles cmdText.Click
        ' Get the text from the text box.
        Dim LocalText As String = TextBox1.Text
    
        ' Convert and display the text.
        LocalText = ConvertText(LocalText)
        MessageBox.Show("Uppercase Text is: " & LocalText)
    End Sub
    
    Public Function ConvertText(ByVal Text As String) As String
        Return Text.ToUpper( )
    End Function
    
End Class

Symbolic rename works with any property, class, or method name you want to change. Here are a few important points to keep in mind about how symbolic rename works:

• If you rename a class, all the statements that create an instance of that class are also changed.

• If you rename a method, all the statements that call that method are also changed.

• If you change a variable name that is the same as a method name, only the variable is changed (and vice versa).

• If you change a local variable name that is the same as a local variable name with different scope (for example, in another method), only the first variable is affected.

The symbolic rename feature isn't immediately impressive, but it's genuinely useful. Particularly noteworthy is the way it properly observes the scope of the item you want to rename. For example, when you rename a local variable, your changes don't spread beyond the current procedure. On the other hand, renaming a class can affect every file in your project.

Note that if you change the name of a control variable, your code will also be updated accordingly. However, there's one exception—the names of event handlers are never modified automatically. For example, if you change Button1 to Button2, all the code that interacts with Button1 will be updated, but the event handler subroutine Button1_Click will not be affected. (Remember, the name of the event handler has no effect on how it works in your application, as long as it's connected with the Handles clause.)

Tip

In Visual Studio 2005, when you rename a .vb file in the Solution Explorer, the name of the class in the file is also renamed, as long as the file contains a class that has the old name. For example, if you rename Form1.vb to Form2.vb and the file contains a class named Form1, that class will be renamed to Form2. Any code statements that create an instance of Form1 will also be updated, no matter where they reside in the project. However, if you've already changed the class name to something else (like MyForm), the class name won't be affected when you rename the file. In Visual Studio 2002 and 2003, the same action of renaming a form file has no effect on your code, so it's worth noting.

What about...

...support in Visual Basic 2005 for C# refactoring? Unfortunately, many of the additional refactoring features that Visual Studio provides to C# programmers don't appear in Visual Basic at all. Symbolic rename is one of the few new refactoring features that's alive and well for VB programmers in this release.