Rename a Visual Studio Project

I care about silly things.  One of those is naming convention consistency, and so I somewhat regularly find myself needing to change the name of Visual Studio projects. From the IDE, it is actually quite simple to rename a project file.

First, select the project.  In this example, we are renaming “HelloLibrary” to “Hello.Utilities”:

Hit F2 (or right-click and select “Rename”) and enter your new name:

Hit enter and you’re done! Well… almost.

If you’re following the standard convention, your project is laid out on the file system roughly like this:

• Hello.World
  • Hello.World.sln
  • Hello.World
    • Hello.World.csproj
  • HelloLibrary
    • HelloLibrary.csproj

When we changed the name of the “HelloLibrary” project from the IDE, all that really happened on the file system was that the file “HelloLibrary.csproj” had its name changed to “Hello.Utilities.csproj”.  To satisfy our OCD, we really want to change that folder name from “HelloLibrary” to “Hello.Utilities”. Unfortunately, the IDE won’t do that for us.  We’ll have to do it manually.

Start by saving your work in VS.  You need to save so that VS will write out the change it has made to your solution file.  Then exit VS, as it tends to get grumpy when you modify file paths out from under it.

Next, navigate to your project in explorer, and change the name of the folder to match the new project name:

If we were to open the solution file now, VS wouldn’t be able to find our “Hello.Utilities” project, because it isn’t aware of the new path:

To get VS to recognize then new path, we need to manually edit the solution (“.sln”) file.  Open it up in a text editor. I am partial to Notepad++, but good ol’ notepad will do the trick.  Don’t be scared of working with the solution file manually; it is actually quite easy to read.  Basically, the solution file is just a glorified list of project files:

Note that our earlier change in the IDE has already changed the file name and the project name (from “HelloLibrary” to “Hello.Utilities”). We simply need to modify the path to reflect the folder rename:

Save the solution file in your text editor.  Now, when we open the solution back up in VS, everything is once again right with the world:

Once you’ve opened the IDE, make sure to do a “save all” so that VS will save its modifications to the projects that depend on the renamed project.  Like solution files, project files also include relative paths to project references, but VS will “fix” these automatically for you; we don’t need to change them manually, but we do need to save the fix made by VS.

Congratulations!  You have successfully renamed a Visual Studio project and its containing folder. However, we haven’t completed the job quite yet.  You will want to change the “Assembly name” (i.e. the name of the dll generated when your project compiles) and the “Default namespace” for the project.  These settings can be modified in the IDE from the “Application” tab of the project “Properties” screen (right-click the project and select “Properties”):

Finally, you will want to update the namespaces of existing classes in the project to reflect the new name.  This can be a tedious task, but luckily, ReSharper has an automatic refactoring to handle it for you.

To review, here are the steps we followed to properly change a project name:

1. Change the name of the project from the IDE
2. Save the solution and close Visual Studio
3. Rename the folder containing the project using explorer
4. In a text editor, edit the solution file to reflect the new folder name
5. Re-open the IDE and “save all” to update dependent projects
6. Update the “Assembly name” and “Default namespace” to reflect the new name
7. Modify existing namespaces to reflect the new name

Step 1 can be done outside the IDE if you like. If you start by changing the project file name in explorer, you will just have to manually change the project name and file name in the solution file as well.

It is important for the quality and maintainability of your software to keep names up-to-date and consistent.  The difficulty of “properly” changing an assembly name in Visual Studio is a big impediment to doing that.  I wish it were easier (there is probably room for some VS extensions to help out here). However, once you get the hang of the full process to do it the “right” way, project renames will become less daunting and you’ll be willing to do “housekeeping” on your project names more regularly.