Initial Umbraco Site Setup

In a previous blog I went through the software that I needed to install to get to this point on my new laptop. Here I’ll detail the process I went through to get an Umbraco site up-and-running locally.

Create a local database

I created a database on my machine using SQL Server Management Studio (SSMS). By default, it has been set up to use Windows Authentication to connect to my SQL Server installation, so I just hit the “Connect” button on the login popup.

On the left-hand side of the window, the “Object Explorer” can be seen, this contains a folder-like tree of all the components that can be manipulated using SSMS. Right now, we are only interested in creating a new database, if we right-click on the “Databases” we can select the top entry “New Database…”.

Set the “Database name” to whatever you require (I chose rtmullinger2018SQL2017), leave the rest of the fields at their default values (unless you know better) and hit “OK” to create the database. You should see the database appear under the “Databases” node in the Object Explorer tree. Keep a note of the name that you used.

Create a Web Application Project

It is now time to launch Visual Studio and create the project that will become the new website. Open Visual Studio and select File→New→Project from the menu (there may also be a shortcut on the Start Page shown). In the tree on the left-hand side ensure that you have “Visual C#” selected and select “ASP.NET Web Application (.NET Framework)” as the project template. Select your project Name, Location and Solution name and make sure that you have “Create directory for solution” checked. We’ll come back to Source Control later, but you can check that checkbox if you want to set it up now. Hit “OK” and we’ll specify some more details.

For the extra details, use the “Empty” project template and leave all the checkboxes unchecked, unless you want to add some unit tests. Press “OK” to create the project.

Installing Umbraco

It’s now time to add the Umbraco code to our new project. For this we’ll use NuGet, which allows us to manage packages that are added to our project. On the right-hand side of the Visual Studio window you’ll see the “Solution Explorer”, which contains a tree of the files and folders in the project. In there, right-click on the top-level “Solution” node and select “Manage NuGet Packages for Solution…”.

A new “NuGet-Solution” tab will open up in the main part of the Visual Studio Window. Along the top of this window you will see a number of different sections (Browse, Installed, Updates, Consolidate), click on “Browse” and type “umbraco cms” into the search box. Click on the “UmbracoCms” (not the “.Core” one) and select the project in the right-hand part of the tab.

Note, that the version of Umbraco that you see is very likely to be different to the one shown above. Umbraco is very actively developed, and new versions are released every few weeks.

Click on the “Install” button to add Umbraco to your project. You will need to confirm the installation and license agreements. It will take a few minutes to install Umbraco, you can monitor the progress in the “Output” section at the bottom of the Visual Studio window. It will indicate when the install is finished, and you will also see the Umbraco “Readme.txt” file in the main part of the window.

Configuring Umbraco

The project can now be run, as this is the first time Umbraco will take over and ask you for configuration information. Make sure the “Solution” is selected in the Solution Explorer and Ctrl-F5 to run the project in your default browser.

A new tab will be opened in your default browser and an Umbraco page will load, asking you for your name, email and password. This will be the Umbraco master user, which will have special privileges and cannot be changed, so it is a good idea not to use your personal email address for this – we can always create a user for you later.

Click on the “Customize” button to continue. You can choose the default option if you want, it will use a SQL CE database and have a standard Umbraco starter site set up.

On the following page select “Microsoft SQL Server” as the Database type, set the Server to “localhost”, and enter the name of the database that you created above. Click “Use integrated authentication” if you set up SQL Server using the default settings.

Click on “Continue” and agree to configure the ASP.NET Machine Key and choose not to install the starter site (unless, of course, you want to). After a few minutes of Umbraco knowledge gems, you will see the Umbraco back-office and the CMS has been successfully installed.

Back Office URL

By default, you access the Umbraco back-office using the /umbraco URL. I’m not very keen on this, because it means that automated tools can easily tell that it’s an Umbraco site. I always like to change it as follows.

Within the Solution Explorer click on the “Show All Files” button and then the “Refresh” button to ensure we’re seeing the true list of files.

Right-click on the project (the level below the solution) and select “Open Folder in File Explorer”. I prefer to do file manipulation in File Explorer, I always seem to run into trouble if I do it through Visual Studio. In File Explorer take a copy of the “Umbraco” and rename it to something relevant for your site, I’m not going to share what I chose, but an example may be “contentadmin”.

Back in Visual Studio you can hit refresh again, and you’ll see the new folder. We can now update web.config to tell Umbraco to use “/contentadmin”, rather than “/umbraco”. Update “umbracoReservedPaths” and “umbracoPath” to use your new folder rather than “umbraco”.

If you now run the project again you can see that Umbraco now uses the new URL. Note, that after writing this blog I have found that some packages rely on the /umbraco path, so doing this for a project isn't always possible. You can easily change it back at any time.

Source Control

It is a very smart move to record all the changes that you make to a project. To do this you can add it to a source code control system. At work we use Team Foundation Server, but it seems like Microsoft now suggest Git, an open-source alternative. I decided to go with that.

Git stores all of your files, and all of the changes made to them, in a repository. The repository can be cloned to many different places for sharing, thus, there is no need for a centralised server to store all of the project information. There is plenty of information online about how Git works.

To create a repository for a project in Visual Studio, right-click on the top-level “Solution” in the Solution Explorer and select “Add Solution to Source Control”. You will see in the “Output” section that the repository has been created.

A default set of the project files will have been added to the repository, I’m not quite sure of the reasoning behind the choice. From experience I have learnt not to include certain files. I’ll give my reasons below, but first we need to see the full project tree. If you didn’t already click on “Show all Files” and “Refresh” in the previous section, do so now.

The first step is to include certain files in the project. This updates the .csproj file. For each folder/set of files below, right-click and select “Include In Project”. If any files have the ignored (red no-entry symbol) right-click on them and select “Add Ignored File to Source Control”.

It should then turn to a plus sign.

Here are the list of folders/files to include and why.

/App_Data/packages

The files under this section detail the packages that have been installed using Umbraco. They contain information that is required by other developers when looking under the projects section in Umbraco.

/bin

Theoretically NuGet will manage the DLLs and there is no need to include them in source control. However, I have found that it doesn’t necessarily include all of the DLLs required to run the project, and it can be a pain having to go back and individually include the ones it has missed. I therefore include all of the DLLs except the project ones (in my case rtmullinger2018.*). Don’t include the .xml and .pdb files.

/config

Contains all of the configuration files for Umbraco. I’m not sure why, but config/splashes never seems to be included. I’m unsure what it does, but I include it anyway.

/Media

This folder will hold all images and documents that are uploaded into the Media section of the Umbraco back office. The images and documents themselves will not be held in source control as they are content and can differ between the different installations of the code. However, I do include the Web.config file under this folder.

/Umbraco or /contentadmin or whatever you have named it

The copied and renamed folder that contains the Umbraco code must be included. If you have left it unchanged as /Umbraco then just include that. If you have changed the name then include the copied folder. Note, even if you remove the “Umbraco” folder, it will be put back by NuGet. It’s okay not to include it in source control.

/Umbraco_Client

This is the code for the Umbraco back office and it all needs to be included.

/Views

These will contain the front-end (HTML) code for the site and all need to be included.

Top-level files

All of the files in the top-level folder need to be included.

We now need to add the initial version of the project to the repository. Click on the “Team Explorer” tab and select the changes button. Git will first prompt you to save your user information, which will be recorded each time you commit changes to the project.

You’ll see a tree of the changes that Git is proposing to commit to the repository. Among them will be files that are not in the above list. They must be removed by right-clicking and selecting “Unstage” and then (under the “Changes” section, “Ignore these local items”). For my install I had to unstage and ignore the following.

/App_Browsers
/App_Data/Logs
/App_Data/NuGetBackup
/App_Data/TEMP
/App_Data/umbraco.config (the main Umbraco cache file)
/Umbraco (unless you want to keep using it)

You also need to ensure that any of the files that are listed above as being needed in source control are staged (right-click and then “Stage”).

We are now ready to commit the changes to the repository. Enter a commit message and click on the “Commit Staged” button.