[This is one of a series of posts about my experience building a live site with Umbraco 5.]
This is a crucial step. If you don’t setup your development environment right, you’ll find yourself back-tracking a lot.
There is only one good way to develop with Umbraco 5 (U5) and that’s with Visual Studio (VS). U5 is designed to play very well with MVC 3, to the point that you can build your own MVC application that runs right alongside U5 and uses the U5 API for all or part of the content management. Now you can certainly create and edit everything you need to build your site using U5’s web interface, but doing so won’t get you the great intellisense and static code analysis with Razor and C#. In addition, if you are a developer, you can only step into the debugger if you are launch the website via VS.
It’s possible to install the U5 and run it out of VS as a Website project, but that takes a bit of work (we’ll do that later in this post). It’s easier to install U5 with WebMatrix and then move to VS and it has the advantage that you can simply erase the installation and start over quickly if something goes awry. So what follows is a slightly roundabout way of achieving the desired state.
Note: Since I wrote this, the Umbraco documentation folks have produced a much better installation guide that uses NuGet. Look here: http://our.umbraco.org/documentation/v501/Getting-Started/Installing-Umbraco-with-NuGet You should use that if you’re looking for a Visual Studio-only type experience, instead of the roundabout way I describe here.
- Download Umbraco and unzip it into a folder called say U5RTM.
- Right click on the U5RTM folder and select Open as a website with WebMatrix. This will open the site in WebMatrix and give you a link you can click on to launch the install process:
SQL CE, SQL Express or SQL Server?
At this point you have to choose between different databases. This comes down to personal preference. I prefer to work with SQL Express and export the data (via Tasks > Export Data in SQL Server Management Studio) to my test/staging/production environment which runs a full-blown SQL Server. Using SQL Express also let’s me do things with SSIS. However, a lot of people like the fact that backing up a SQL CE database is as easy as copy pasting a .SDF file.
I am going to use SQL Express here, which involves providing a full connection string to the database server. Follow through with creating an administrator account and you should be able to get into the site.
If everything works well, you are now ready to make this a VS project.
Setting up the project in Visual Studio
This step used to be time consuming. You see, Visual Studio project files are really build scripts for a tool called MSBuild, so they have all this metadata about what type of project something is and a list of every single resource that needs to be included into the compilation or build process. Creating this by hand is a pain, so it wasn’t worth doing.
Now, however, there is this really nice pre-configured project on Our created by Sebastiaan that comes with a project and a solution file. Follow those instructions, but instead of downloading U5 as it says on that page, simply copy paste all the sources from the U5RTM folder into the Umbraco.Web folder. I called my solution folder Website, and both projects that you get from Sebastiaan’s package are in it.
Now when you open the project in VS, you may find that some files and/or folders are not included in the project. This happens because Sebastiaan’s original project only includes the original sources that you get when you download U5, not the additional folders/files U5 creates during installation. If you’d like to include these resources, simply right click on the files/folders and click Include in Project. At this point, this is how your project structure will look (ignore the App_code folder which you won’t have – we’ll get to it in a future blog post):
Now when you launch the project, U5 will start off just like any MVC 3 project.
What about source control?
Ok I lied about something. Before even copying anything into my Website folder, I setup Git as my source control system. In true GitHub fashion, I added a Readme.md file that contains some information about the project. At this point, Here’s how my directories look:
(Yes I am using ReSharper. You don’t need it to develop with U5, but if you aren’t using it, you’re really spending a lot more time than you need to on coding.)
Where’s the connection string?
After all this, if you open up Web.config in Umbraco.Web to take a look at the connection string, you won’t find it. That’s because U5’s connection string is actually part of the provider that provides database capabilities (more on that in a future blog post). The configuration for that is located in the HiveConfig folder as shown below:
Notice that connection.config? That’s a file you won’t have by default, because that’s something I added. In order to ensure that I don’t accidentally commit the connection string to the source control system, I extracted the connection string out using the configSource property and added the connection.config file to .gitignore. Here’s how that looks:
And the connection.config then looks like this:
At this point, I push the entire folder into my master repository and take a deep breath, knowing that all my work is safe from catastrophe.
That’s it. Now you can launch the project from VS, debug, create partials and views inside VS, etc and U5 and VS will play nicely with each other.
Next time, I’ll talk about how to think like an Umbracian.
UPDATE (with correction!):
@andythompson asked me 1) what my .gitignore looks like and 2) how I publish with this method.
Here’s my .gitignore, in its entirety:
That’s a list of directory paths separated by a new line.
BUT WAIT, THERE’S MORE: The way git works, you need to put a .gitignore file in every directory where you have assets that you want git to ignore, unless you are planning to commit the entire source tree every time. I actually did this, but totally forgot about it when I posted this update. When I went back to developing on my site, I realized to my horror that I’d forgotten to mention this key point. Apologies! So here are my other .gitignore files:
The .gitignore in App_Data looks like this:
# Don't need logs in repo
# This keeps track of minification, etc and is on a per-machine basis.
and the one in App_Data/Umbraco/HiveConfig looks like this:
# This file contains connection strings so it should not be committed to the repository.
The way I publish this site is by doing the simply right-click publish onto FTP/local file system. The environment I use doesn’t support WebDeploy so I have to do it this way. As for the database, I used the Export task in SQL Server Management Studio:
Yeah it’s not the smoothest process, but I am moving towards setting up continuous integration via TeamCity so at some point this will happen hands-free on every commit.