When I started working for Umbraco we had a large but manageable community of people building sites with Umbraco and figuring out the best solutions for their problems with our software. Problems? Yes, we have an approximately 15-year old codebase, which had many bugs when I started working at Umbraco we have many bugs we have yet to fix.

We used to be able to mostly keep up with bugs people were dealing with, we more often than not were able to give tips on the forums, on Twitter and in the issue tracker. This is fun and thankful work and I still love helping out whenever I can.

However, these days, with the amount of people using our software, this is no longer manageable. Many people want to use our software and this is great. I still love to help people but I can't dive into every problem in depth, nor can my colleagues. This is why we offer support contracts, if you need help and you're willing to pay for it then you get to jump the line of people who also want help but are not willing to pay for it.. or not able to pay for it. Your money allows us to hire and train more people to help out!

But that last category of people, the ones that simply cannot pay for priority support are sometimes out of luck. We have a wonderful community, donating a lot of their spare time to try and help out. But their time is also limited and they will not always be able to give you a solution either. 

Most of the time we will spend the time to pick up high priority problems that affect a lot of Umbraco users anyway, so most people are not left high and dry when there's bad bugs.

On the other hand, the problem you're facing might only apply to you, or it has a workaround that's acceptable to most people or it only applies to a particular setup that we are unable to replicate. What to do?

Contributing to open source software

As a developer myself, I use open source tools that help me do my job better or easier. I often get annoyed or blocked by some bug in the software. So, I like giving back!

Over the years I've contributed to projects like Git Extensions, lets-encrypt-win-simple, ACMESharp, ImageProcessor, UmbracoTracelogViewer and other projects. Some of these were directly related to work I was doing for Umbraco, most in my spare time.

And here is where I have a confession to make: most of my contributions initially were born out of pure frustration. Bugs that were annoying, features that didn't work the way I liked them, missing features, etc. So that's the dirty truth: I mostly contributed out of pure selfishness. 

However, the happy outcome of these contributions has always been: a change for the better, not just for me but for all the other users of that software. It may come as no surprise but it feels really, REALLY good to help turn that frown upside down!

Help yourself

So, dear Umbraco users, let me give you some tips on how you can help yourself (and help us in the process!). You are in the unique position to investigate your particular problem.

By digging into the specific bug you're encountering you can give us a hint or some proof of where our code is doing something wrong, You might even be able to send us a pull request so we can look at it and go "ha! how could we have been so silly as to believe that would ever work correctly?". After which we'll happily click the "Merge" button to get your code into the next release of Umbraco and you potentially make many people's life better!

Here are a few steps you should take:

1. Identify the exact problem

What exactly is happening?

It's like going to the doctor: if I press here, it hurts here. The better you can describe which steps you take to get into an unwanted situation, the better your chances that it can be fixed.

2. Pinpoint the problem

Following up to point 1: is it just you?

Download a fresh copy of the Umbraco version you're running and install it without any plugins and without your custom code in there. Follow the same steps you took to identify the problem (see point number 1). Do you still see the problem? If not, the problem is likely a configuration difference, due to some plugin you installed or caused by some of the custom code you wrote.

At this point I usually start to compare configuration files and if they're the same, I'd start taking some custom components out of the site, to see if I can narrow it down to some plugin or to some of my own code.

3. Eliminate the problem

Is the problem fixed already?

If you see an error message: Google it, add the word "Umbraco" in quotes to your query to get the best results. Is there an issue on the issue tracker with a "Due in version" set? Is the version higher than the version you're running now? Time to attempt an upgrade to see if the problem is already fixed! Take a backup of your site and database, upgrade the backup to the latest version and try steps 1 and 2 again.

Hint: issues on the tracker almost always point to the code we changed, it might give you a good idea of if your particular problem is going to be fixed.

4. Investigate the problem

Did none of the above help? Time to get your hands dirty! This is where the fun part starts! 

Each Umbraco release is tagged when we release it, so you can find the particular version you're using and get the exact source code for it. You can clone the Umbraco repository and with a command like `git checkout tags/release-7.4.2` you would get to the exact code that your Umbraco 7.4.2 site is using right now. 

With that code, you can now do great things! Open up `umbraco.sln` in Visual Studio and build it. The build output will not only give you the same dlls you are using right now but also the pdb files, the symbols to debug the code.

If you go into the `~/src/Umbraco.Web.UI/bin` directory you can find the files that were just modified.

Go ahead and copy these files right into the problematic website. You now have full debugging capabilities for that website, while maintaining the exact functionality that was in our dlls in the first place! 

Back in Visual Studio you can attach it to the process that is running your website, for example IISExpress (the easiest way) or the w3wp process.

Now you can set breakpoints in our code to narrow down that problem that's been annoying the heck out of you!

Pro tip - if your problem only occurs on the live server and you cannot attach to the process to set breakpoints: add copious logging to the areas you suspect of having problems, update the dlls on your server with the new ones that add logging and see what you can find.

5. Report back to us!

Hopefully by now you will have figured out the root cause of your particular problem, or at least you got closer to it. You should be able to tell us in great detail (describing the previous steps in depth) what the problem is and maybe even how we could fix it.

At this point people sometimes feel like they've spent too much time on this already and tell us: the code in file x on line y is wrong; you should change it from a KiloJoule to a Pancake.
This doesn't really tell us very much though, you might be right but to us a KiloJoule doesn't look like a Pancake at all so we would love to hear the process that led you to this conclusion. The more details you can give the easier we can help get this fixed.

We love pull requests, send us the fixed code so it's easy for us to look at it, get embarrassed about our silly mistake and accept that fix as quick as we can.

Hint: unit tests are a great way to prove your fix does what it says it does and doesn't break something else. Not required, but much appreciated.

If you can't provide a unit test: be as detailed as you can in your description.

Avoiding rabbit holes

Aha, now you have the power!

Something you should be careful of: changing loads of code. We understand, more than anyone, that our code might make you angry, that it's all wrong and not following best practices. There are reasons for this. We are dealing with legacy code, some of it might go away soon. We have coding styles that you may hate, we understand (even within our team there's the constant I Hate #Regions battle).

Rarely will we accept a code clean-up pull request. It is not very useful, and might lead to a refactor gone wrong which introduces subtle bugs. 

We also know that you are really missing feature X and you know exactly how to build it and, by golly, you're doing it, sinking a month's worth of weekends into it, emerging with a beautiful pull request.

We understand, completely, but.. talk to us first! Please, before you go down a rabbit hole, discuss it first, open an issue on the issue tracker, describe what you want to do and make sure we want you to do it.

It is always a good idea to lobby for an issue/feature by asking around about it on Twitter and adding a discussion in the dedicated forum "Contributing to Umbraco CMS". This should give you a bit of an idea of how useful other people think your proposal is.

Remember: we can't put everything in Umbraco, some things are much more suitable for a plugin. We would love to guide you.

Conclusion

The power of open source software is that you can poke at it, you can look into everything that's happening behind the scenes and get and better understanding of a problem you're having. That understanding may even lead to a bugfix, which would be great. But if anything, it will teach you something and by poking at problems in our code, you're not just helping yourself grow, eventually you might also help someone else, or many people in the process. 

The true power of OSS is that by being selfish and helping yourself, you can turn that frown upside down for many people. 

The best part about lews is that I can read the source code and understand what's going on, hurrah for keeping it fairly simple! The second best part was that I could really quickly develop a plugin for it. What I wanted to do is to fully automate obtaining the certificate. Currently it's not yet possible for me to automate the install of the certificate but (at Umbraco) we're working at making that possible as well.

If you've read my previous blog post, you know that Let's Encrypt needs to verify that you own the domain you're trying to purchase a certificate for. Let's Encrypt tells you to put a file in your site with a verification token in it, that they can then read. I used to do this manually but it became tedious, so I wrote a quick ApiController so I can just tell my site: create a file, in folder x with content y. One warning though: this is VERY insecure. I've only secured it with a secret token right now but if you post to this endpoint over http, your request can be intercepted and random files can be written to your website!

Right. A quick test with Postman later and I'm confident that I can now automatically create the verification that Let's Encrypt needs.

Now I need to tell lets-encrypt-win-simple (can we just rename this to Lewis?) how to use this endpoint. Lewis (there, I did it!) allows for plugins to be built, just make a class that inherits from `LetsEncrypt.ACME.Simple.Plugin` and implement the methods you get. I took a peak at their FTP plugin and borrowed some code from that one.

In order to show up in the lews dialog you need to implement a `public override void PrintMenu()` method that tells you something like: "X: press x for my plugin". Then you can handle the keypess in a HandleMenuResponse method that you override and in which you test if "X" has been pressed. That's it, we're in business! We can now do whatever we want.

A bit of code:

Results in an extra menu option:

The prompt here is a bit deceiving, but instead of giving it a host to get a certificate for, you enter one of the menu options.

The code then needs to create a target (basically: a hostname for which to create a certificate) and call the `Auto` method, passing in this target:

    public override void HandleMenuResponse(string response, List targets)
    {
        if (response != "c".ToLowerInvariant()) return;

        var target = new Target
        {
            Host = "cork.nl",
            WebRootPath = string.Empty,
            PluginName = Name
        };

        Auto(target);
    }

Of course you wouldn't have hard coded domains in there, this is just a proof of concept to see if it works.

Then it get's really interesting, Lewis (I always imagine people with the name Lewis have a moustache) will look for a method called `CreateAuthorizationFile` which is where we can call our endpoint with the directory name to create and the contents of the authorization file:

    public override void CreateAuthorizationFile(string answerPath, string fileContents)
    {
        const string token = "not_my_real_secret";
        var endpoint = new Uri("https://cork.nl/umbraco/api/Certificate/ValidationFile/");
        var directoryName = answerPath.Split('/').Last();
        var parameters = string.Format(
            "DirectoryName={0}&FileContent={1}&Token={2}", directoryName, fileContents, token);

        using (var web = new WebClient())
        {
            web.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
            web.UploadString(endpoint, parameters);
        }
    }

 This makes Let's Encrypt happy and they send me a certificate!

Though I am happy with this result, I do wish I could do all this with just a few command line switches so that I don't need to manually tell Lewis (it's sticky, isn't it!) what to do every time I start it. Full automation is on their roadmap and I've sent them a simple pull request to get started. For now, I'll work with my fork which has this logic in it already.

What's not covered in this post, is the `Install` method, in which you can code how exactly to install the certificate on your target server. You can get some inspiration from the built-in plugins for that of course!

All in all, I'm happy that things are moving fast on the Windows side of Let's Encrypt and we'll definitely have a bright and encrypted future ahead of us!

Background

First let me start with a note on how UaaS currently works. When you create a new project you get 2 websites: a development environment and a live environment. The development environment has a git clone URL so you can get the website down to your machine and start building locally.

Once you're happy with the results you push the "end result" back to the development site, check that it's all working as expected and then you can push your changes to the live website.

The reason I said "end result" is because this is what your cloned website will basically look like locally:

You will note that there's a distinct lack of Visual Studio files, nor is there any code folders in there. In the UaaS documentation we refer to this as our "deployment repository".

When we started building Umbraco as a Service we of course had lofty goals of supporting all types of projects that could "just" be pushed to UaaS and we would take care of the rest. The option above is ONE of the possible options we worked on and currently the only one. It's the most simple one: give us an "end result" website and we'll make sure it works on UaaS.

Of course when you have lofty goals, at some point reality will catch up on you.. which it did for us. After all kinds of experiments with VS solutions in the git repository and Grunt/Gulp/Bower/Npm/etc. we realized that this would take significant extra effort to make work well. There were many other aspects around the automation experience that we would have to focus on as well, for example:

• The baseline feature (which complicates things if you start throwing in VS solutions, and javascript package managers)
• Server resources; if UaaS starts being a build server, we need many more resources to be able to do this acceptably fast
• Reliability; we need to make sure that all kinds of build setups work and run, we need to install pre-requisite software for that
• Speaking of reliability: eventually builds will fail, so we'll need to build ways to debug, try again, clean up etc.

We're a small team and don't have infinite resource to do all of this right now. We very much wish to still offer more advanced deployments but we have to choose to keep it simple for now. I think we currently have a happy medium on top of which we can build over time.

So, for now, we have a requirement that says: if you're a Visual Studio gal or guy, we ask you kindly to build things locally and drop it into the UaaS repository all pre-built. You can verify that it works on your local machine, at which point you can also be confident it works on UaaS once you push those changes up. This is what I mean when I say you push the "end result" up to UaaS (and why it's referred to as a "deploy repository" in our documentation).

This does mean that you're responsible for setting up your own VS environment and you will need to put your custom code in a different source control repository from the one on UaaS. The disadvantage is obvious, you're still going to be responsible for a small part of the infrastructure. Luckily it's easy to outsource that part to Github/Bitbucket/etc these days.

There is also a big advantage of this separation: it will force you to make your code more or less modular which means that you could end up dropping the same code into a different site and it will mostly "just" work. It might just teach you to blur the lines a little less and think more of separation of concerns.

Automating the setup

Okay, enough talk about how we got here, let's take away my one big annoyance: having to think about how to set up my VS solution. For the automation of this I've thought about how I would want to work: I want to have my website, it should automatically run from VS when I hit F5 and to make it simple, I want it to be a (VS) Website project. The reason to choose a Website project over a Web Application project is to make it reflect exactly what we're looking at, a web site in which we drop custom assets, like a dll with some code we want to add to the site.

So, not:

But:

Speaking of custom code, apart from the Website project I also want to have a (VS) Class library to write my code in that I can build and drop into the website's bin folder. This build and copy should happen automatically once I hit the Play button (debug button) in VS so that I can start putting in breakpoints and debug my code.

Here's where the biggest problem always was for me: I wanted to reference the UmbracoCms.Core libraries from the class library but I could never find a way to set up all the references in a reliable way. NuGet doesn't have a way to install the libraries from the command line either. Not having the references to UmbracoCms.Core would kind of defeat the purpose of automating this. "Hey, use this script to set it up. Oh and hey now you have to go and manually install the NuGet package after that, sorry!". 

I finally accidentally stumbled upon some code from someone who managed to install NuGet packages from C# meaning it could now be fully automated!

Team

Alright, so where are we now: 

1. Create a new project on Umbraco as a Service
2. Download and run the Visual Studio automation script

Tada! We have a UaaS site running in VS and we can immediately start being productive.

Note: If you don't know what Puppy Monkey Baby is.. I am still confused too.

That leaves us with one thing for which we don't have the optimal solution yet: sharing this with your team. Right now this is a bit harder then we want it to be due to the restrictions I told you about earlier in the "Background" section. But I think it's manageable for now. 

We do try to help as much as we can though: while running the VS automation script, an empty git repository was also set up for you and a .gitignore file was added so you can start committing your new site immediately and push it to whichever git hosting you prefer. The ignore file will ignore anything that's going on in your deployment repository (the .Web folder, containing the "end result" site for UaaS).

So for a team member to get set up, you now have a 2-step process:

1. git clone `your custom code repository`
2. git clone `UaaS git url` 

Conveniently, you also get a UaaSClone.cmd file in the root for that second step, so they don't have to go to the UaaS portal to go and find the git URL. They can just double click UaaSClone and go. The end result should look something like this:

So:

• Git repository for your custom code
• NuGet packages folder for the packages installed into YourNameSpace.Core
• YourNameSpace.Core - where your custom code goes
• YourNameSpace.Web - the "end result" / deploy repository with the Umbraco website in it
• Git Ignore file using a default Visual Studio ignore plus an added rule to ignore YourNameSpace.Web
• The Visual Studio solution file
• UaaSClone.cmd for your colleagues to execute to get a copy of YourNameSpace.Web in the correct place

Try it now 

So, without further ado: download the batch file and start playing.

You will need to enter the git clone URL that you can find in the UaaS portal for each of you projects and a namespace for Visual Studio. The process is captured in a video below (recommend watching in full screen and at least 720p to be able to read the text):

Note that the script is something that has only just in the past few days fully materialized so there may be rough edges. We wanted to put this out there so people can have a play with it and we can receive feedback for the team to build on this. So please, provide us with feedback to make your experience better. Leave comments below!

By chance, it took a long time to download the actual complete site they were trying to upgrade but I had the database backup on my machine already. Then it occurred to me: I don't really need the website, just the database!

Imagine you're upgrading from Umbraco 7.0.4 to 7.4.2, here's what you do (warning: blink and it's over!):

• Install a fresh copy of Umbraco 7.4.2 using SQL server
• When it's done, go into your web.config and:
  • Change the version from 7.4.2 to 7.0.4
    • the Umbraco upgrade installer then knows: okay, I need to run every available migration between versions 7.0.4 and 7.4.2
  • Change the connection string to point to the database that you want to upgrade (the one that's still on version 7.0.4)
• Run the upgrade installer that kicks in automatically
• Done!

Of course you still need to upgrade the actual website with the new files and do your config merges etc, but at least you know that your custom code is not blocking the database upgrade any more.

Told you: blink and it's over!

This is where Umbraco migrations come in. Migrations were introduced in version 6 of Umbraco to help us change database schema's during an upgrade of Umbraco. Migrations use code instead of using SQL upgrade scripts, while scripts are nice they are limited to executing SQL. We realized that sometimes there's a need to execute some code during upgrades as well. For example: we sometimes want to migrate data that is difficult to handle in a SQL script but would be really easy to deal with using a bit of code.

As of Umbraco version 7.3 these migrations are also very useful for making schema changes in different environments by just deploying your code, no more need to write manual SQL scripts that need to run on each environment.

How it works

In the Umbraco database we have a table called umbracoMigration that tracks which migrations have ran for that specific database, so on a fresh 7.4.2 install you'd see the following:

When Umbraco starts, the first thing it does is that it gets the current version of Umbraco using `Umbraco.Core.Configuration.UmbracoVersion.Current` which in this case is 7.4.2 but when you update the Umbraco dlls to version 7.4.3 it will return 7.4.3. If Umbraco then cannot find the migration with name "Umbraco" and version "7.4.3" in the database, you will get the upgrade installer screen. 

Once you click the Continue button Umbraco goes and finds all of the classes that have a `Migration` attribute with a version between the newest version in the `umbracoMigration` table and the `Umbraco.Core.Configuration.UmbracoVersion.Current` version. For example, if I've upgraded my Umbraco dlls from 7.3.5 to 7.4.2 it would find migrations targetting versions higher than 7.3.5 and lower than or equal to 7.4.2.

We don't do any migrations for patch releases, only for minor and major versions (remember a version is: major.minor.patch). So in reality the upgrade from 7.3.5 to 7.4.2 would only find migrations targeting version 7.4.0 like the ones above. After these have been executed, a new entry will appear in the `umbracoMigration` table, indicating the latest migration that ran on this database. For the Our Umbraco database, for example, you can see exactly which upgrades were done when:

The important part to understand about this is that when you deploy your website to the next environment, it will do this same comparison: find `Umbraco.Core.Configuration.UmbracoVersion.Current` and compare that to the highest migration in the `umbracoMigration` table. They will be different because the migration only ran on our local environment. You will again see the upgrade screen on your website, click continue and the migrations run on that environment after which the upgrade is complete. This means that any environment you deploy to will be consistent. 

Sidenote: we didn't always use to do this and people would often forget to run the upgrade installer after deploying their upgraded website from local to the next environment. Most times this wasn't a problem, but when there was actually changes to be made to the database they might have been forgotten, leading to an inconsistent database, leading to problems later on. This is also why you sometimes see database upgrade errors when these migrations run, at some point the proper changes were not made to your database years ago, leading to wrong assumptions on our end and an inability to upgrade your database.

You too can do this

Long story short: migrations are great! Now let's see how you can utilize them.

The table that I mentioned in my previous blog post could, for example) consist of a nodeId (a reference to a page in Umbraco) and a count (the number of times this page was visited). In this example we're going to be Umbraco's ORM called PetaPoco, and when using that, we can describe the table we want to use in a C# class like so:

 using Umbraco.Core.Persistence;

 namespace Example.Models
 {
   [TableName("Statistics")]
   [PrimaryKey("nodeId", autoIncrement = false)]
   public class Statistics
   {
     [Column("nodeId")]
     public int NodeId { get; set; }

     [Column("count")]
     public int Count { get; set; }
   }
 }

In order to build a migration, we can make a class that has the `Migration` attribute and inherits from `MigrationBase`. Inheriting from that requires you to implement the `Up()` and the `Down()` methods, for doing and upgrade and, if necessary, a downgrade.

using Example.Models;
using Umbraco.Core;
using Umbraco.Core.Logging;
using Umbraco.Core.Persistence;
using Umbraco.Core.Persistence.Migrations;
using Umbraco.Core.Persistence.SqlSyntax;

namespace Example.Migrations
{
  [Migration("1.0.0", 1, "Statistics")]
  public class CreateStatisticsTable : MigrationBase
  {
    private readonly UmbracoDatabase _database = ApplicationContext.Current.DatabaseContext.Database;
    private readonly DatabaseSchemaHelper _schemaHelper;

    public CreateStatisticsTable(ISqlSyntaxProvider sqlSyntax, ILogger logger) 
      : base(sqlSyntax, logger)
    {
      _schemaHelper = new DatabaseSchemaHelper(_database, logger, sqlSyntax);
    }

    public override void Up()
    {
      _schemaHelper.CreateTable<Statistics>(false);
 
      // Remember you can execute ANY code here and in Down().. 
      // Anything you can think of, go nuts (not really!)
    }

    public override void Down()
    {
      _schemaHelper.DropTable<Statistics>();
    }
  }
}

The migration attribute needs to be provided with a version number, since we're just starting out this is set to "1.0.0". The next argument is the sort order, if there's multiple migrations necessary to upgrade to "Statistics" version 1.0.0 you can run them in the correct order. We use the `Statistics` class we created to describe the table earlier to create or drop the table.

Finally, we need to make this migration run. Since the attribute has the third argument "Statistics" it will not run and trigger when you upgrade Umbraco, only migrations with the name "Umbraco" run automatically. So we need to run it manually somehow. In the future we want to change Umbraco so that it also runs your custom migrations through the Umbraco upgrade installer, for now you'll need to handle it yourself.

In order to run this, we can create an EventHandler that runs when Umbraco starts. In this event handler we will look for the newest migration that ran for the "Statistics" product to check if we need to actually run any migrations. If the database tells us: version 1.0.0 of "Statistics" has been ran, we do nothing. If the version doesn't exist or is lower than the current version, we of course need to run the migration to get the database in a consistent state.

using System;
using System.Linq;
using Semver;
using Umbraco.Core;
using Umbraco.Core.Logging;
using Umbraco.Core.Persistence.Migrations;
using Umbraco.Web;

namespace Example.Eventhandlers
{
  public class MigrationEvents : ApplicationEventHandler
  {
    protected override void ApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
    {
      HandleStatisticsMigration();
    }

    private static void HandleStatisticsMigration()
    {
      const string productName = "Statistics";
      var currentVersion = new SemVersion(0, 0, 0);

      // get all migrations for "Statistics" already executed
      var migrations = ApplicationContext.Current.Services.MigrationEntryService.GetAll(productName);

     // get the latest migration for "Statistics" executed
     var latestMigration = migrations.OrderByDescending(x => x.Version).FirstOrDefault();

     if (latestMigration != null)
       currentVersion = latestMigration.Version;

     var targetVersion = new SemVersion(1, 0, 0);
     if (targetVersion == currentVersion)
       return;

     var migrationsRunner = new MigrationRunner(
       ApplicationContext.Current.Services.MigrationEntryService,
       ApplicationContext.Current.ProfilingLogger.Logger,
       currentVersion,
       targetVersion,
       productName);

     try
     {
       migrationsRunner.Execute(UmbracoContext.Current.Application.DatabaseContext.Database);
     }
     catch (Exception e)
     {
       LogHelper.Error<MigrationEvents>("Error running Statistics migration", e);
     }
   }
 }
}

Note: for versions before 7.4.2 you'll need to build in an extra `catch` as Umbraco was doing something silly, which is now fixed. So before the `catch (Exception e)` you can add a specific `catch`

catch (System.Web.HttpException e)
{
  // because umbraco runs some other migrations after the migration runner 
  // is executed we get httpexception
  // catch this error, but don't do anything
  // fixed in 7.4.2+ see : http://issues.umbraco.org/issue/U4-8077
}

Cool, we now have a new table we can use and the migration has been noted for our local database. When we deploy this site, the migration will run again as it's not been recorded in that database yet.

Just as some code to test this I've added the counter to my Master template so it will execute on each page, it's not great architecture but it at least allows me to do some quick testing.

@{
   Layout = null;

   var database = ApplicationContext.Current.DatabaseContext.Database;

   var query = new Sql()
       .Select("*")
       .From<Statistics>()
       .Where<Statistics>(x => x.NodeId == Model.Content.Id);

   var result = database.Fetch<Statistics>(query).FirstOrDefault();

   if (result == null)
   {
     database.Insert(new Statistics { NodeId = Model.Content.Id, Count = 1 });
   }
   else
   {
     result.Count = result.Count + 1;
     database.Update(result);
   }
}
<span>Views: @(result == null ? 1 : result.Count) - NodeId: @Model.Content.Id</span>

And after a few refreshes of the page I can see that this works like a charm.

And in our browser:

Now imagine you want to count things in different categories, like PageViews, Downloads, Clicks, etc. You can still use this table but you might want to add a category name to it so you can track different types of counters. 

First, we can update our `Statistics` class and add the Category there. 

  [Column("category")]
  public string Category { get; set; }

Then we can add a new migration that adds a column to the existing table.

using Umbraco.Core.Logging;
using Umbraco.Core.Persistence.Migrations;
using Umbraco.Core.Persistence.SqlSyntax;

namespace Example.Migrations
{
  [Migration("1.0.1", 1, "Statistics")]
  public class AddCategoryToStatisticsTable : MigrationBase
  {
    public AddCategoryToStatisticsTable(ISqlSyntaxProvider sqlSyntax, ILogger logger) 
      : base(sqlSyntax, logger)
    { }

    public override void Up()
    {
      Alter.Table("Statistics").AddColumn("Category").AsString().Nullable();
    }

    public override void Down()
    {
      Delete.Column("Category").FromTable("Statistics");
    }
  }
}

The last thing we need to do is tell the EventHandler that we're expecting our "Statistics" product to be of a new version now, 1.0.1. Note that the migration above is also created to update the product to version 1.0.1.

    var targetVersion = new SemVersion(1, 0, 1);

When this runs we can see in the `umbracoMigration` table that, once again, the migration ran. We also see the new column on the `Statistics` table that we have there.

A quick update of our code now allows us to log the category of our counter as well.

@using Example.Models
@using Umbraco.Core.Persistence
@inherits UmbracoTemplatePage
@{
   Layout = null;

   var database = ApplicationContext.Current.DatabaseContext.Database;
   var category = "PageView";

   var query = new Sql()
       .Select("*")
       .From<Statistics>()
       .Where<Statistics>(x => x.NodeId == Model.Content.Id && x.Category == category);

   var result = database.Fetch<Statistics>(query).FirstOrDefault();

   if (result == null)
   {
     database.Insert(new Statistics { NodeId = Model.Content.Id, Count = 1, Category == category });
   }
   else
   {
     result.Count = result.Count + 1;
     database.Update(result);
   }
}
<span>Views: @(result == null ? 1 : result.Count) - NodeId: @Model.Content.Id</span>

Conclusion

This post was very much inspired by a recent question on the forum and the answers there, where I learned not to do this in a "hacky" way.

In this article we've seen that we can create migrations, "things" that need to be executed once on each environment that you deploy your website to. These "things" could be database tables, but you could also imagine that you might want to add a property to a document type, anything is possible. Migrations can help you make sure that all of your environments are in a consistent state when you deploy it to the next environment.

Instead, this post focuses on making sure your performance on Azure is optimized.

Sync Examine indexes

First and foremost there's something you need to understand about how the server structure is set up behind Azure Web Apps (AWA). The two most important servers in the setup are the Web Worker (the machine that has IIS on it which is hosting your site) and the File Server. Whenever a new website on AWA spins up, it gets assigned to a Web Worker which has enough capacity to run another web site on it, there may be dozens / hundreds of other sites running on it. Sometimes the Web Worker needs maintenance at which point your site will be re-allocated to another available Web Worker and your site will move there. I say "move" but there's one important thing to understand here: the files used in your website live on the File Server and not on the Web Worker. All that the Web Worker does is it sets up a network path (UNC path) and tells IIS: there you go, my files are here. This points to the File Server, not to a path on the local machine, even though a UNC path very much behaves like a local path.

Why is this important? One word: latency. Every time the Web Worker gets instructed to change a file on disk it has to reach out over a network connection to a different server and make that change. This is a relatively slow process. You will not notice this latency when doing "normal" operations like, for example, saving a template in Umbraco.

However, where you will notice this latency is when it comes to disk operations that need to be highly performant. One of the best examples here in both read and write latency are the Examine indexes. Umbraco comes with a Lucene.Net implementation called Examine and it is fast.. really fast. It can be this fast because it relies on speedy access to it's data, the stored indexes on disk. Each time you ask for a media item, a query gets sent off to Examine to find the media item quickly. Each time you save a document in Umbraco, the saved information gets sent into Examine to be indexed. Each time you build a custom Examine searcher and use it.. you get the idea.

So, long story short: you want your Examine indexes to live on the local disk of the Web Worker instead of on the remote File Server. This can be done as of Umbraco 7.2.8 by adding the following attribute to all of your indexers and searchers: useTempStorage="Sync".

Update: it has come to my attention that, for now, it's best not to include the machine name in your ExamineIndex.config, so if you've previously added that you might want to consider removing that for the time being. Note that your indexes will be rebuilt when you do this, so if this is a long process make sure to plan for some downtime. More information can be found in this forum topic.

The 'Sync' setting will store your indexes in ASP.NET's temporary file folder which is on the local file system (so: on the Web Worker). Any time the index is updated, this setting will ensure that both the locally created indexes and the normal indexes are written to. This will ensure that when the app is restarted or the local (Web Worker) temp files are cleared out that the index files can be restored from the centrally stored index files (on the File Server). If you see issues with this syncing process (in your logs), you could change this value to be 'LocalOnly' which will only persist the index files to the local file system in ASP.Net temp files.

Setting the indexes to "Sync" will ensure that your websites starts as fast as it can after it's been moved to a new Web Worker, the indexes will be copied from the File Server to the Web Worker during application startup. If you set the setting to "LocalOnly" your indexes will only ever exist on the Web Workers and thus need to be rebuilt every time your site is moved to a new Web Worker. This could work just fine for most sites but there's no performance to be gained from it and if you have a large index, this may slow down your website on startup significantly as it needs to rebuild all of the indexes from scratch.

FcnMode

Shannon has written an in-depth blog post about File Change Notifications already so I'm not going to repeat that. We have shipped with `fcnMode="Single"` since Umbraco 7.3.5 and you should also set that attribute on your system.web/httpRuntime element in your web.config.

We have made this change to all of our Web Workers on Umbraco as a Service too and to quote Shannon from that blog post above:  

To solve this issue we changed fcnMode=”Single” in the machine.config so that all sites would effectively use “Single”… and the result was instant: No more constant app restarts, file server performance was instantly back to normal. And as far as I can tell, there has been no downside to running FCNMode in Single.

That blog post is now 6 months old and with ~2000 sites still happily running at great performance we're now confident that fcnMode="Single" is the only way to run any ASP.NET website. If you're on Umbraco versions older than 7.3.5, you can just add this attribute yourself, it will work on any version of Umbraco.

Logs

Umbraco uses Log4Net for logging debug information and errors. A few people with very active sites have found that the logger started slowing down the website so much it was easily noticeable and the performance hit could be tracked back to the logger. This occurred even though the logger was asynchronous and "shouldn't" have affected website performance. Since version 7.3.0 we've been shipping with a new logger that should take more of the stress off of your website. Even so, we do log a lot of information and all that logging can quickly start taking up a lot of disk space. 

We recommend at least for your live website to set the Log Priority to "WARN" instead of the default "INFO" and when the site has been running well for a while and you're comfortable you could even swith to "ERROR".

Debug

It's your live environment. So what do you do in your web.config? Yes, indeed, you set debug mode to "false" and customErrors mode to "RemoteOnly". Right? Right! You also built your dlls in Release mode before deploying them, right? Right!

What else

Far be it for me to say that you might have produced some badly performing code. You're a professional programmer who has been at it for years and you know exactly what you're doing, right? Well on the off chance that you had a minor glitch in your brain, maybe you should check to make sure.

The biggest offense we see these days is people using the ContentService and other Services in their frontend queries. Please, please don't do this, it goes straight to the database and kills your performance, especially if you make queries as crazy as: find the root node and then query all of it's descendants (that's ALL nodes in Umbraco!) to find the property "thisIsAnAmazingArticle" and then ToList() it and show only the first article with this property set to true. Stop. :)

Another thing that seems to be a pattern (and it's certainly an anti-pattern) is that people make the exact same mistake that I once made for Our Umbraco's download section: I needed a download counter.. so, hey I know: let's add a property "counter" on each Download Document Type and save & publish the Download page each time someone downloads this version, increase the counter with 1. Trust me, this doesn't scale. Ever. Please do not put counters on your document types and increase them programmatically. It's just as much work to create a simple table with a `nodeId` and `count` column and update that one with a bit of PetaPoco.

Caching can be super useful if you know that you need to do something that you can't optimize the performance of right now (or ever). Use Umbraco's Macro caching, or Umbraco's ApplicationCache, or implement Donut Caching, etc. Even a very short cache of a few minutes can make a world of difference if you have 10 requests per second doing the exact same work 10 times. Note, however, that caching really should be a last resort after you've tried to optimize as much as you can. With caching comes cache invalidation and that can be hard or even dangerous.

Also, I won't JUST blame you: we have had some issues with Umbraco performance and some, let's say "interesting" bugs in older versions. Make sure to upgrade to the latest version of Umbraco that you can upgrade to. If you have to stick with patch upgrades then 7.2.8 and 7.3.8 are both considered stable, but if you can do minor upgrades, definitely consider going to at least 7.3.8. Of course if you like receiving regular update, then going to version 7.4.2 and keeping up with the latest versions would be much preferred (remember, I blogged about upgrading Umbraco recently as well).

Microsoft also makes mistakes, this one is a pretty huge bug and you need to be aware of it and manually install the patch if you're using Windows Server 2012R2.

Conclusion

This post is partly the result of questions and answers gathered over the last few months in this forum post, it might be good to read through that to find some more specific examples that might apply to your situation. I hope this helps you optimize you Azure hosted Umbraco site (pro-tip: a lot of these tips also help on any other hosting provider). 

I'm not going to explain how to create a binding in IIS, this process is different per hosting provider and it's impossible to cover this for everyone. We've made it easy on Umbraco as a Service (UaaS): upload a .pfx file, bind it to one of your host names. We can (and will) make it even easier.

Alright, we're there, our site, when typing "https://" as the prefix works and gives us a satisfying green lock to show that the connection was encrypted end to end and Chrome tells us our site is secure, yay!

There's only one more thing that you need to do for Umbraco to make sure that the backoffice is secure: go into your web.config and find the appSetting called "umbracoUseSSL". This setting is "false" by default and needs to be changed to "true". A quick look in the source code of Umbraco teaches us that the only use for this setting is to make sure that the cookies issued when logging into the backoffice get the "secure" flag, meaning it will only send the cookie when the connection is encrypted (so only over https).

This is all it does, and that's all there is to it, you've secured your Umbraco site!

Taking it further

We're running successfully on https, but we might not be at the peak of our game yet, let's run some online scans to see what else we can do to make our site more secure.

SSLLabs

Okay, that was the good news. Full of hope you run over to SSLLabs to test your site's security. Depending on your hosting server's setup you might and come up with a.. disappointing grade. Luckily, my site lives on Umbraco as a Service, so I get a mighty fine "A" grade.

Hoever, you might end up with a different grade if the server your hosting on has enabled insecure protocols and encryption ciphers. If you're self-hosting then I recommend you run Nartac IIS Crypto and apply the fixes suggested using the "Best Practices" button. It's a dead-simple, one-click fix for most (if not all) of your bad grades on SSLLabs.

HTTPS by default

For the following modifications, I'm going to assume that the URL Rewrite module for IIS is installed on your webhosting server (exactly why Microsoft doesn't ship with this installed by default is beyond me!).

Now that we can access the site over HTTPS, let's redirect all traffic to the site to HTTPS, that way you always have that happy green lock in your browser and you will always encrypt all traffic against people trying to snoop on you whether they are a Man In The Middle, your internet provider or the NSA. This can be done using a URL Rewrite rule. In the following rule "localhost" is excluded from rewriting so that I don't have to jump through hoops to set up valid certificates and hostnames when debugging my site on my local machine.

This configuration goes into the system.webServer/rewrite/rules section of the web.config:

 <rule name="HTTP to HTTPS redirect" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
   <add input="{HTTPS}" pattern="off" ignoreCase="true" />
   <add input="{HTTP_HOST}" pattern="localhost" negate="true" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
 </rule>

While we're adding redirects, it's good for search engines to have just one domain to look at, so I can set up a redirect that strips "www" from any requests (which will then feed into the rule above and makes sure to redirect to HTTPS):

 <rule name="Strip www. from URL" stopProcessing="true">
  <match url="^(.*)$" ignoreCase="true" />
  <conditions logicalGrouping="MatchAll">
   <add input="{HTTP_HOST}" pattern="^www\.(.+)$" />
  </conditions>
  <action type="Redirect" url="http://{C:1}/{R:1}" redirectType="Permanent" />
 </rule>

To further minimize any attacks where bad guys might want to trick you into using insecure HTTP request, you can send up a header with each request called the HTTP Strict Transport Security (HSTS) header. Enabling HSTS will tell the browser: for the specified amount of time you will not look up any pages on this domain over HTTP any more, always use HTTPS. This is an addition that can be made to the system.webServer/rewrite/outboundRules section:

 <outboundRules>
  <rule name="Add Strict-Transport-Security when HTTPS" enabled="true">
  <match serverVariable="RESPONSE_Strict_Transport_Security" pattern=".*" />
  <conditions>
   <add input="{HTTPS}" pattern="on" ignoreCase="true" />
   <add input="{HTTP_HOST}" pattern="localhost" negate="true" />
  </conditions>
  <action type="Rewrite" value="max-age=63072000; includeSubDomains; preload" />
  </rule>
 </outboundRules>

This adds the "Strict-Transport-Security" header that tells browsers: for the next 63072000 seconds (which is two years) the browser should not make any HTTP requests to this domain.

Note: the rules for HSTS inclusion might change from time to time. Make sure to read the current requirements before you follow these steps.

However... there's still a tiny sliver of an attack vector here. If you are a Man in the Middle and manage to lure someone to a site that they've never visited before, their very first request will still be the only one ever to go over HTTP. In that single request the Man in the Middle could still possibly do bad things. The only way to eliminate this risk is to never allow HTTP connections to the site, but then everybody needs to know that you can only ever get to the site by prefixing it with "https://". Not very user friendly.

You can, however, ask to be put on a list that is baked into browsers like Chrome, Firefox, Safari, IE11 and Edge. This is called HSTS Preloading and takes a few weeks to get set up (it's a manual process). When you do finally make it on this preloaded list, your browser will never request any pages over HTTP but choose HTTPS by default. Part of the manual check that Google will do is to see if HSTS is set up including subdomains and if the preload parameter is there, this is why they're added to the rewrite rule above.

ASafaWeb

The "Automated Security Analyser for ASP.NET Websites" will test your Umbraco site for known issues with ASP.NET websites. I'm not doing so well on this one and have a few things to fix.

AsafaWeb gives me excellent guidance to fix things like Custom Errors and an exposed Stack Trace, just update the web.config to set Custom Errors to "RemoteOnly" and we're good.

As for the orange warnings:

• Excessive headers: The header "Server: Microsoft-IIS/8.5" gets sent with each response. I have tried disabling this but apparently our UaaS servers forcefully add this header. Nothing I could do about it, this needs to be removed at a server level. There's many other ways to probe sites and find out (by looking at their behavior) that it's running IIS and even which version it runs. So attackers specifically out to target my site are only a few seconds extra delayed in picking the correct attack vectors, I'm not worried about this header.
• HTTP only cookies: The "ARRAffinity" cookie is only there for IIS to quickly determine on which of the available web servers my website lives. It's not an attack vector: if it's wrong or doesn't exist, this cookie will just be overwritten with a new one.
• Clickjacking: A valid concern, I can deny people framing my site with the simple addition of "X-Frame-Options" to the web.config (more on this later!).
  Note: Always make sure you remove a custom header first, if the webserver already has it's own "add" rule, then you can't overwrite it by inserting your own, you need to remove the existing one first. Also note that Umbraco has tried to be helpful and removed the header that tells the world what MVC version you're running by removing "X-Powered-By" in the systemWebserver/httpProtocol/customHeaders section of your web.config.
  

   <httpProtocol>
    <customHeaders>
     <!-- Ensure the powered by header is not returned -->
     <remove name="X-Powered-By" />
     <remove name="X-Frame-Options" />
     <add name="X-Frame-Options" value="DENY" />
    </customHeaders>
   </httpProtocol>

There's a few gray boxes there: because my site doesn't have a view state in the HTML, AsafaWeb assumes (correctly) that I'm not using WebForms, so those tests didn't need to run any further. I couldn't figure out how to trigger the "Hash dos patch" test, even after adding a form that does a POST (as described on AsafaWeb) it doesn't test for this problem. Luckily I know that UaaS runs on servers not affected by the MS11-100 security vulnerability, but you might want to check with your hosting provider.

Looks better now:

Security-headers.io

Going even further down into securing our website, there's some "fun" things we can do to make most websites misbehave, like making it do the Harlem Shake.

Security-headers.io looks to see if you've implemented policies to mitigate these kinds of problems which are mostly XSS (cross site scripting) based. Look at this result.. ouch:

We can easily makes this a lot better by following some of the advise here on adding a "X-Xss-Protection" and a "X-Content-Type-Options" header:

 <httpProtocol>
  <customHeaders>
   <!-- Ensure the powered by header is not returned -->
   <remove name="X-Powered-By" />
   <remove name="X-Frame-Options" />
   <add name="X-Frame-Options" value="DENY" />
   <remove name="X-Xss-Protection" />
   <add name="X-Xss-Protection" value="1; mode=block" />
   <remove name="X-Content-Type-Options" />
   <add name="X-Content-Type-Options" value="nosniff" />
  </customHeaders>
 </httpProtocol>

Better:

The Content Security Policy (CSP) is a lot harder to implement because it requires you to look at all of your site's assets and whitelist them. This is difficult especially if you load video's from YouTube, use CDN hosted javascript libraries, links to external images etc. Which brings us to the following check to run.

CSP Analyser

The CSP analyser over at report-uri.io looks at any policies you've implemented and tells you how good they are. It's impossible to give a good policy for all websites, so I'll just post the one I've struggled with and finally landed on for this site:

 <httpProtocol>
  <customHeaders>
   <!-- Ensure the powered by header is not returned -->
   <remove name="X-Powered-By" />
   <remove name="X-Frame-Options" />
   <add name="X-Frame-Options" value="DENY" />
   <remove name="X-Xss-Protection" />
   <add name="X-Xss-Protection" value="1; mode=block" />
   <remove name="X-Content-Type-Options" />
   <add name="X-Content-Type-Options" value="nosniff" />
   <remove name="Content-Security-Policy" />
   <add name="Content-Security-Policy" value="default-src 'self' https://www.gravatar.com;script-src 'self' https://www.google-analytics.com https://ssl.google-analytics.com;style-src 'self' 'sha256-MZKTI0Eg1N13tshpFaVW65co/LeICXq4hyVx6GWVlK0=' 'sha256-CwE3Bg0VYQOIdNAkbB/Btdkhul49qZuwgNCMPgNY5zw=' 'sha256-LpfmXS+4ZtL2uPRZgkoR29Ghbxcfime/CsD/4w5VujE=' 'sha256-YJO/M9OgDKEBRKGqp4Zd07dzlagbB+qmKgThG52u/Mk=' https://fonts.googleapis.com;img-src 'self' data: https://www.gravatar.com https://www.google-analytics.com;font-src 'self' https://fonts.gstatic.com https://fonts.googleapis.com;" />
  </customHeaders>
 </httpProtocol>

I am using Gravatar images, Google Analytics and the Google Fonts API. The sha256 references are there to fix some things that Modernizr.js wants to execute, which wouldn't otherwise be allowed, Chrome dev tools will tell you exactly what to add if this is a problem for you:

To make it a bit easier for you to manage, report-uri.io allows you to set up a free account. Using that, all CSP violations will be logged for you so you can have a look at updating your whitelist accordingly.

After setting up a CSP, securityheaders.io now reports a respectable "A" grade.

I've looked into Public Key Pinning (HPKP) but the process seems too onerous for little gain for now. The problem with HPKP is currently that I don't understand how backup CSRs are supposed to work and what exactly I need to do when my current certificate expires. I have done some experiments and they worked but I need to do further testing to see what it will take to switch to a new certificate.

In case you are wondering (and are brave), the HPKP header can be configured like so in system.webServer/httpProtocol/customHeaders:

 <remove name="Public-Key-Pins" />
 <add name="Public-Key-Pins" value="max-age=31536000; pin-sha256=&quot;h2EVK2+bga6XAxu7ImUQM0PJsgZd2/a2VtlcSmV87s4=&quot;; pin-sha256=&quot;9ilXj1leytbsCvXVIFJ1uzjmej2bzs05qzRzmfFzXKs=&quot;; pin-sha256=&quot;nupZBiNmjIMxIyEll+OBYjvMORUEyYTTr7K5bE2z7L0=&quot;;" />

Note that the double quotes need to be escaped because the web.config file is an XML file, so replace " with " everywhere in the value of this header.

Back to Umbraco

Now that we've made our frontend all nice and safe, let's go back into the backoffice of Umbraco.

Whoops, we broke it!

There's a few things going on in the backoffice that we need to allow now that we've disallowed a lot of them on the frontend. Umbraco still uses iframes for some pages in the backoffice so we'll need to allow those. The Content Security Policy is also blocking a lot of asset loading because they're set pretty strict on the frontend.

Luckily we don't have to change our frontend setup, we can just change the backoffice requirements a little bit. All the way at the bottom of our web.config we already have a <location path="umbraco"> section which tells IIS: for this location (the umbraco path) we want to apply different rules then for the rest of the site. We can amend this section with a custom CSP and allow frames from the same origin (so only frames with a location that lives somewhere in our site).

We're already disabling urlCompression for the backoffice as that can conflict with our backoffice javascripts, so let's add our updated headers there:

 <location path="umbraco">
  <system.webServer>
   <urlCompression doStaticCompression="false" doDynamicCompression="false" dynamicCompressionBeforeCache="false" />
   <httpProtocol>
    <customHeaders>
     <remove name="X-Frame-Options" />
     <add name="X-Frame-Options" value="SAMEORIGIN" />
     <remove name="Content-Security-Policy" />
     <add name="Content-Security-Policy" value="default-src 'self' www.gravatar.com player.vimeo.com *.vimeocdn.com packages.umbraco.org our.umbraco.org;script-src 'self' 'unsafe-inline' 'unsafe-eval';style-src 'self' 'unsafe-inline';img-src 'self' data: www.gravatar.com umbraco.tv;font-src 'self';" />
    </customHeaders>
   </httpProtocol> 
  </system.webServer>
 </location>

Much better, our backoffice is back without errors.

One interesting thing I found when implementing CSP rules is that I was not allowed to have inline CSS in my site, this is a good thing, I don't want inline CSS, I want everything to be nicely tucked away in a CSS file.

One problem though: the rich text editor. When you insert an image in the RTE, Umbraco automatically adds an inline style for you with the dimensions of the image and there seems to be no way to prevent it from doing so. 

I've created a simple extension method that goes through your html and strips out those inline styles. This StringExtensions.cs can be dropped into your App_Code folder:

using System.Web;
using HtmlAgilityPack;

namespace Cultiv.StringExtensions
{
  public static class RteStyles
  {
    public static IHtmlString RemoveInlineImageStyles(this string text) 
    {
      var htmlString = new HtmlString(text);
      return htmlString.RemoveInlineImageStyles();
    }
 
    public static IHtmlString RemoveInlineImageStyles(this IHtmlString htmlString)
    {
      var htmlDocument = new HtmlDocument();
      htmlDocument.LoadHtml(htmlString.ToString());
      if(htmlDocument == null || htmlDocument.DocumentNode == null || htmlDocument.DocumentNode.SelectNodes("//img[@style]") == null) 
      {
        return htmlString;
      }
      else
      {
        foreach (var node in htmlDocument.DocumentNode.SelectNodes("//img[@style]"))
        {
          var attribute = node.Attributes["style"];
          node.Attributes.Remove("style");
        }
      }
      return new HtmlString(htmlDocument.DocumentNode.OuterHtml);
    }
  }
}

I use it as follows in my templates:

@(Model.Content.GetPropertyValue<string>("bodyText").RemoveInlineImageStyles())

Conclusion

Security is hard. :-)

Luckily there's plenty of tools that help ease the pain. We are always looking into updating Umbraco where possible to take away the pain by setting up sensible defaults. We're also working on making things easier to set up on Umbraco as a Service where we can rely more on automation.

There's a few security related sites I should point to that are excellent in helping you understand security and keeping you safe:

• Follow Troy Hunt's blog and Twitter account (or whatever social media you like, there's plenty of icons on his site)
  • If you have a PluralSight account, his security courses are always great as well 
• Follow Scott Helme's blog and Twitter account
• I enjoy the Security Now podcast for regular in depth discussions of how security works (and most notably: where it fails, of course) and recommend playing it at 1.5 speed

Finally: there's a lot more you can do to protect your site, but this is a mammoth post already so I'll end this here in hopes that I get more time in the future to cover related topics.

First of all: we test upgrading for every Umbraco version we release. We upgrade the solution we use for masterclasses, we upgrade Our Umbraco and when there's big changes we upgrade a bunch of other random sites too. So when it doesn't work for you, it's most likely that something went wrong on your computer, not in our upgrader. I'm not blaming the "victim" here, but just want to make you aware that we do all we can to make your upgrades succeed the first time. We miss stuff sometimes though, and that sucks, in which case we either try to correct that quickly or at least document it. 

We also document how to upgrade your site as comprehensively as possible, so make sure to read the documentation, loads of hints and tips that we keep up to date:

• The general upgrade guide
• The version specific upgrade guide

Needless to say: you have your code checked into source control (or at the very least backed up before you upgrade) and you've made a full database backup before upgrading your site, right?

Troubleshooting

With that out of the way: shit happens! So let's try to figure it out.
I like to think of the Umbraco ZIP downloads as the "known good" state; when you have "problem x" after upgrading and installing a clean Umbraco install does not have "problem x" then something most likely went wrong with your upgrade.

Most people these days use NuGet for installing and upgrading Umbraco, that's also where most people have problems as it LOOKS like everything is done automatically for you, but sometimes it hasn't worked. NuGet can have a temperament where it "forgets" to do config transforms, runs into problems while doing the upgrade or "forgets" to copy certain files.

Time to debug! Let's start with the 3 C's: configs, cache and cookies.

Configs

Check that your config files in the ~/Config folder have been updated, and especially check if both your web.config files (the one in the root of your site and the on in the ~/Views folder) have been updated. How? Aha! Here is the best tip I will give you in this blog post: download a copy of BeyondCompare and import these settings. Finally, make sure to click the "Ignore unimportant differences" button, which hides unimportant whitespace differences.

Right, with a beautiful BeyondCompare install in place, download the zip file corresponding to the Umbraco version you're trying to upgrade to. Right click the zip file and choose "Select left folder for compare", then find the folder where your Umbraco install lives, right click it and choose "Compare to UmbracoCms.x.y.z.zip". You'll get a nice overview of folders and some will disappear as they're the same on both sides, leaving you with just the differences.

The first thing I usually check is the root web.config to make sure that everything that might be new in the Umbraco default web.config file is in the web.config file in my site. A special section to pay attention to is the runtime/assemblyBinding one that really needs the bindingRedirect versions to be correct.

After you've updated config files: try again, your site probably works just fine now.

Extra tip: while you're comparing it's also a great moment to check that all the required files are in your bin folder, we ship with what's needed in the zip file so make sure that all the files on the left side are also on the right side and that the versions are the same. Again, BeyondCompare only shows you the differences between the two folders so it should be easy to spot if anything is amiss.

Note: Yes, I know this is possible with WinMerge and other compare tools as well, but BeyondCompare is so much better than all of the others.

Cache

No? Okay then, try clearing your browser cache. Umbraco uses a lot javascript/angular/html that changes for most releases. The first thing to check: ~/Config/ClientDependency.config. Change the version number in that file (just make it 1 higher or lower) and try again. This should clear client side cache for most browsers.

However.. Chrome in particular is super aggressive in caching so it might not make a difference. So, for another hot tip in this post: if you use Chrome, hit the F12 button and the reload button next to the address bar is a little bit magical now. Try right-clicking on it...

You now have options! The best one of which is: Empty Cache and Hard Reload. It does what it says on the tin and requests all assets completely freshly and should load whatever is updated in Umbraco.

Cookies

We recently had a problem where an old cookie would throw a spanner in the works. Again, the developer tools in your browser can come to the rescue, I have the most experience with Chrome so again, hit the F12 button and go to the resources tab to find and delete all cookies.

Other problems

Check your log files, in ~/App_Data/Logs/ - whenever there's any kind of error that we can log, it will be in here. Look for things that look suspicious in the last few minutes that you were working on your upgrade and then do the simplest thing possible: copy an error and paste it into Google. You won't believe what happens next! (sorry.. I'm so sorry..).

Over the years Umbraco has had some let's say "interesting" database upgrades. Since v6 we have made this much more consistent and when the Umbraco upgrade installer runs we try to anticipate all the exotic database schema variations we had in the past and make everything consistent again. If you see database errors during an upgrade, it's likely that you're not the first person to see it, google it and see if there's manual workarounds. We try to pick up all of these errors and fix them in the next version so they don't pop up any more.

We sometimes break things, when it's on purpose we list them as being breaking changes on the release page of the version you're trying to upgrade to, if there's multiple versions between your current version and the version you're upgrading to, you might have to read up on all of the release pages to see if anything broke due to a change we made. So say you're upgrading from 7.3.6 to 7.4.1, make sure to read the release notes of 7.3.7, 7.3.8, 7.4.0.

But why?!

Yes, we do hear you cry "why can't it just work?!". Well, mostly: people do wildly different things with Umbraco. We learn every day and when we learn about something new and unexpected, we update the upgrade installer. This is an ongoing process that will never be perfect but it so much better than it was a few years ago. The NuGet experience these days is almost seamless and I encourage everyone with a new project to start out with a NuGet install and stick with it (even though it has grumpy days sometimes). It's well worth investing time in learning how NuGet works and what it does.

Automatic upgrades

Oh, and one more thing, on Umbraco as a Service, you get automatic upgrades. So you don't have to worry about any of this. You just wake up one day and see a message in the portal and continue making great sites for your clients.

Update: this is getting much easier already, check out the follow up post to this one.

So I was very excited to learn about a year ago about the formation of Let's Encrypt. As they describe it: "Anyone who owns a domain name can use Let’s Encrypt to obtain a trusted certificate at zero cost.".

Awesome! They have some good sponsors and I'm donor for the Electronic Fronteer Foundation, which started this initiative so in a way, I'm still paying for my certificates, sort of. ;-)

I was super excited this week to see that Let's Encrypt was in public beta now and wanted to play with it! But.. of course all of the official tooling focuses on Linux environments and it's been a while for me since I used that. So, I found a cool little project on GitHub called ACMESharp, implementing the protocol and APIs used by Let's Encrypt using PowerShell.

It took me a while to wrap my head around it but it all makes sense now after playing with it for a while, there's really only 3 steps:

1. You have to agree to the terms of service
2. You have to prove that you own the domain that you want a certificate for
3. You request the certificate

The documentation for ACMESharp gave me some clues as to how this works but there was still a few "gotcha" moments there. I'll lead you through the PowerShell script that I came up with:

Import-Module -Name D:\Temp\ACME-posh\ACMEPowerShell.psd1
$domain = "cork.nl"
$certificiatePassword = "abcd1234"
$email = "letsencrypt@cork.nl"
$vault = "D:\Vault\{0}\{1}" -f $domain, [guid]::NewGuid()
mkdir $vault
cd $vault

Some setup cruft - first of all, you download the ACMESharp release that's available and unzip it somewhere and import the module you find in there. I make a new folder for each attempt at running this script by generating a new GUID each time.

Next up: pointing to the public beta server that will give you a real, trusted certificate. At first the URL I had here was still pointing at the staging server which gives you cerificates issued by "happy hacker fake CA". Needless to say: I can't use those in production.

Initialize-ACMEVault -BaseURI https://acme-v01.api.letsencrypt.org/
New-ACMERegistration -Contacts mailto:$email
Update-ACMERegistration -AcceptTOS

The terms of service are accepted here and I give them my email address, this was a little confusing as I was waiting for an email to come in to click the "Accept TOS" link but it didn't come. Good, because this is now fully automated, I can just tell them in PowerShell that I accept the terms of service, which I obviously studied closely (not!).

Okay, now the fun part starts: verifying that you own the domain. You ask Let's encrypt to give you a secret randomly generated blob of text that you, as the site owner can put on your website.

New-ACMEIdentifier -Dns $domain -Alias dns1
New-ACMEProviderConfig -WebServerProvider Manual -Alias manualHttpProvider -FilePath $vault\answer.txt
Get-ACMEIdentifier -Ref dns1
$completedChallenge = Complete-ACMEChallenge -Ref dns1 -Challenge http-01 -ProviderConfig manualHttpProvider

Note: the FilePath variable in New-ACMEProviderConfig doesn't exist in the 0.7.1 release. I created a pull request to add that to ACMESharp and it was accepted an hour later (yay!). If you use this right now, you'll get an instance of Notepad popping up asking you to complete the FilePath in the bit of JSON that gets put into Notepad. I like automation so I asked if it could just be a variable. 

Now, the Complete-ACMEChallenge command returns all the information you need to complete the challenge, I didn't read this properly at first so I wasn't sure what to do. I did it wrong and then the challenge status was set to 'invalid'. Even after correcting my mistake and following the instructions, it was still 'invalid'. "Damn it! Now I'll never be able to get my certificate..". Or so I thought. After Googling for a bit I found out that once a challenge was marked as invalid once, it would never become valid (there's good security reasons behind this, preventing replay attacks). So the trick is to ask for a new challenge, easy!

I added some output to my PowerShell script to remind me exactly what to do:

$challengeAnswer = ($completedChallenge.Challenges | Where-Object { $_.Type -eq "http-01" }).ChallengeAnswer
$key = $challengeAnswer.Key
Write-Host ""
Write-Host "Create folder structure on $domain like so:"
Write-Host "$domain/$key"
Write-Host "Put an index.html file in that location that contains:"
Write-Host $challengeAnswer.Value

Which outputs something like this:

Create folder structure on cork.nl like so:
cork.nl/.well-known/acme-challenge/V6CPYDViDCk6X3YWC9wH61kKW2CHtQ-SLACnIcBNFPY
Put an index.html file in that location that contains:
V6CPYDViDCk6X3YWC9wH61kKW2CHtQ-SLACnIcBNFPY.8uMzTUtlJpLEsyNHnTmLutOPZyFv4VUCFwaqram0gRo

I can do that! So what needs to happen is when the Let's Encrypt server goes to the URL http://cork.nl/.well-known/acme-challenge/V6CPYDViDCk6X3YWC9wH61kKW2CHtQ-SLACnIcBNFPY the body of the response should contain the secret key: V6CPYDViDCk6X3YWC9wH61kKW2CHtQ-SLACnIcBNFPY.8uMzTUtlJpLEsyNHnTmLutOPZyFv4VUCFwaqram0gRo

In this case I do this by placing an index.html in the created folder as I know that IIS will serve that up by default, your server might be configured differently so make sure that it outputs the secret key somehow (and only the secret key, nothing else). 

Right! Now we can tell Let's Encrypt: I'm ready, please verify:

$challenge = Submit-ACMEChallenge -Ref dns1 -Challenge http-01
While ($challenge.Status -eq "pending") {
  Start-Sleep -m 500 # wait half a second before trying
  Write-Host "Status is still 'pending', waiting for it to change..."
  $challenge = Update-ACMEIdentifier -Ref dns1
}

Here the challenge is submitted and it might take a second for the status to change from "pending" to "valid" so I ask for an update every half second before continuing.

When the status is "valid" we're golden, go get that cert now!

New-ACMECertificate -Identifier dns1 -Alias cert1 -Generate
$certificateInfo = Submit-ACMECertificate -Ref cert1

While([string]::IsNullOrEmpty($certificateInfo.IssuerSerialNumber)) {
 Start-Sleep -m 500 # wait half a second before trying
 Write-Host "IssuerSerialNumber is not set yet, waiting for it to be populated..."
 $certificateInfo = Update-ACMECertificate -Ref cert1
}

Get-ACMECertificate -Ref cert1 -ExportPkcs12 cert1-all.pfx -CertificatePassword $certificiatePassword

Write-Host "All done, there's a cert1-all.pfx file in $vault with password $certificiatePassword for you to use now"

We're asking Let's Encrypt to generate the certificate and then we do another few pings for the IssuerSerialNumber to update, that's when the certificate has been completely generated. Finally we do a Get-ACMECertificate to receive it and it will be stored in the $vault folder. Note: I'm adding a password to this certificate but this functionality is not yet available in the 0.7.1 release of ACMESharp. Again, this was a specific need that I had for which I sent a pull request which was promptly accepted. 

If all this sounds like a lot of work: it is not! 

Now that you understand what's going on, this process is repeatable. Which is very necessary because by default these certificates expire every 90 days and will expire even more quickly in the future. This is being done to promote security: a compromised certificate can now only be abused for a maximum of 90 days. It's also being done to promote automation: I built a PowerShell script so I can automate this, they achieved their goal!

The full PS script is available in a gist for you to copy and use.

Go forth and secure your sites!

Example: In Umbraco 7.1.5, we added some events that get triggered when Partial Views and Partial View Macros get added/saved/deleted through the tree in the backoffice. We wanted to subscribe to those events from Courier but of course that would mean that Courier version "x" would only work with Umbraco 7.1.5 and up. Trying to subscribe to events that don't exist in 7.1.4 would result in a beautiful YSOD. We don't really want to have the headache of deploying different versions of Courier for different versions of Umbraco.

I suddenly remembered Morten referring to a way to having a dll as an embedded resource which could be extracted on demand, he saw this clever little trick happening in the libgit library. So we'll have a look at the Umbraco version and if it's high enough, we'll extract the dll that can subscribe to those new events, if not, we'll just run the good old version and don't do anything else.

So I ran with that and I can tell you: this works!

There's a few steps:

• Add the embedded resource to your solution and change it's path in the csproj file
• During application startup, check the current Umbraco version and extract the file if possible
• When we update the dll, make sure that it's extracted again

So we'll start with adding an embedded resource, which is pretty simple: right-click on the project you want to add the embedded dll to, go to Properties > Resources > Add Resource > Find the file > done.

Now it gets a little trickier: we want the embedded resource to be updated every time we build the project, so that we always have the latest version of the embedded dll in our main dll. First of all you need to make sure that the build of your main dll depends on the build of the embedded dll. In your main project, right click the project > Build Dependencies> Project Dependencies and check on the project that builds your embedded dll.
Then we need to also make sure that this is not just a one-time copy that's being embedded (Visual Studio's default behavior) but that we refer to the path of the dll that's being built. Open up the csproj file of your main project in your favorite text editor and find the line where it says:

<none Include="Resources\MyDllName.dll" />

Change that Include to the path of MyDllName.dll relative to that project directory, for example:

<none Include="..\MyProjectName\bin\Debug\MyDllName.dll" />

Finally, update from "none" to:

<EmbeddedResource Include="..\MyProjectName\bin\Debug\MyDllName.dll"/>

Voilá, the biggest hurdle is taken. The rest is "just" code.

We'll create a new Umbraco ApplicationEventHandler and try extract the embedded dll when the version of Umbraco is 7.1.5 or higher:

using System;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Web;
using Umbraco.Core;
using Umbraco.Core.Configuration;

namespace MyApp.ExampleNamespace
{
    internal class ExtractNewEventHandlers : ApplicationEventHandler
    {
        protected override void ApplicationInitialized(
               UmbracoApplicationBase umbracoApplication, 
               ApplicationContext applicationContext)
        {
            if (UmbracoVersion.Current >= new Version(7, 1, 5))
                ExtractEventHandlers();
        }

        private void ExtractEventHandlers()
        {
            var fileName = Path.Combine(HttpRuntime.BinDirectory, 
                "MyDllName.dll");
            var fi = new FileInfo(fileName);
            
            try
            {
                (Assembly.GetEntryAssembly() ?? 
                    Assembly.GetExecutingAssembly())
                    .ExtractResourceToFile(
                        "MyApp.ExampleNamespace.MyDllName.dll",
                        fi.FullName);
            }
            catch (Exception ex)
            {
                if ((ex is AccessViolationException) == false && 
                    (ex is IOException) == false)
                {
                    throw;
                }
            }
        }
    }
}

The one tricky bit here is that the resource name is a bit weird: it's your default namespace (MyApp.ExampleNamespace) plus the full name of the file you've embedded (MyDllName.dll).

Lastly, we have the extension method ExtractResourceToFile which does the extraction if the file doesn't exist or is different from an existing file.

using System;
using System.IO;
using System.Reflection;
using System.Security.Cryptography;

namespace MyApp.ExampleNamespace
{
    internal static class AssemblyExtensions
    {
        public static bool ExtractResourceToFile(
            this Assembly assembly, string resourceName, 
            string outPath)
        {
            assembly = assembly ?? Assembly.GetExecutingAssembly();

            using (var resourceStream = 
                assembly.GetManifestResourceStream(resourceName))
            {
                var fi = new FileInfo(outPath);
                if (fi.Exists)
                {
                    using (var stream = File.OpenRead(outPath))
                    {
                        if (GetHash(stream)==GetHash(resourceStream))
                            return false;
                    }
                }

                using (var output = File.Create(outPath))
                {
                    int bytesRead;
                    var buf = new byte[4096];
                    resourceStream.Seek(0, SeekOrigin.Begin);
                    while ((bytesRead = resourceStream
                        .Read(buf, 0, buf.Length)) > 0)
                    {
                        output.Write(buf, 0, bytesRead);
                    }
                }
            }

            return true;
        }

        internal static string GetHash(Stream stream)
        {
            var sha = new SHA256Managed();
            var hash = sha.ComputeHash(stream);
            return BitConverter.ToString(hash)
                .Replace("-", String.Empty);
        }
    }
}

And that's about it. On each application pool start, we check if the hash of the file on disk is the same as the hash of the embedded resource, if so we do nothing, else we'll overwrite the file in the bin folder with the new embedded version. And if someone running this upgrades their Umbraco version: boom! They'll get the extra functionality from our embedded dll for free, automagically.

I hope this might help some other people dealing with targeting multiple versions of APIs. However: remember that this is probably not so efficient for very large embedded resources. With great power comes great responsibility so before you go down this route make sure that this method is really what you want and need.

One of the Umbraco tips I always like to give people is to really think about how you build out the backoffice for your editors.
The editors are the actual customers to whom you're supposed to deliver value. They will be spending a huge amount of time in the backoffice and will hate you for every frustrating unneccessary choice that you give them.

Luckily, Umbraco gives you a lot of tools to help out with that so that the editors can enter content as easily as possible. 

The one thing that I always hate seeing is the following:

Or:

Can you spot what's wrong here?

How many times does your editor want to make a news area? In a normal site, there's usually only 1, right? Same for a blog, an FAQ area, and a contact page.

And under the news area you would only add content of type news item, correct? And under the blog, only items of type "blog post".

So why do you allow the FAQ Area under home when it's already been created? Here's a little secret: you don't have to!

Once you've created your news area, your blog and your FAQ area you can just disallow them again. Go to your "Home" document type and don't allow anything but the items your editors actually will be using. 

So now when the editor tries to create something new, they can only make a relevant choice:

 Notice that the blog overview is still there, the contact page is still there etc. And when you try to create new content under blog you can still only create blog posts.

So now you have full control over the site, you know that there's only one blog overview that you need to query for. The children of that blog overview will only ever contain blog posts. There's only one news area, containing only news items. Rinse and repeat.

On the other hand, your editors don't need to think about which item to pick when they click on "create". Less thinking helps them accomplish their tasks faster. If they have no choice then they don't need to be worried about doing the right thing, you've just helped them do it perfectly every time.

Bonus tip: See how each type of document has it's own icon? That is another way to really add value to your sites, visual queues help your editor read less, thus think less, thus they can work faster and are happier with your wonderful site implementation.

I know I can hack paging as inline Razor script in the view but I thought I'd check out what the hype was all about with regards to route hijacking. 

What is route hijacking? Well, it's a way to tell Umbraco that you want to add custom code to certain document types. It can be compared to using partial classes in webforms to insert your own code in masterpages (but better! ;)).

The blog posts are just children of the blog page, as noted in my previous article. Which means that I just need a list of content items and do a bit of .Skip() and .Take() on them before rendering them on the page.

The examples in this post are very simple to keep it readable, but the full examples are available in a Gist as well.

So: this is MVC, which means I'll need three things, guess what they are?

Model

My model mainly consists of content, but also some properties to track the paging (total pages, current page, previous/next page number, etc). I can mix those in with the properties of the current page easily by making my model inherit from RenderBase and asking for the "CurrentPage" in the constructor method.

using Umbraco.Web;
using Umbraco.Web.Models;

namespace Cultiv.Models
{
    public class BlogOverview : RenderModel
    {
        public BlogOverview(IPublishedContent content) : 
          base(content) 
        { }
        
        public int Page { get; set; }
        
        // More custom properties
    }
}

View

The view will have access to all of our custom properties, one if which is the current page number (more on that later, in the controller). The output of the view below will be a header with the page number in it and the name of the current page (which will be "Blog" because this view is rendered on the "Blog" page).

I'm also using the layout that I've created for all the other pages, not using route hijacking. So everything is exactly the same except I have more properties to use. In the final version (not completely included for brevity, I can also do

foreach(var post in Model.PagedBlogPosts) { //etc }

Which is much nicer than

foreach(var post in Model.Content.Children.OrderByDescending(c => c.CreateDate).Take(5).Skip(0)) { //etc }

Note that in order for the view to understand whats going on, it needs to inherit from UmbracoViewPage with the type BlogOverview (again, this is the document type's alias). Here's an example of the view:

@using Cultiv.Models
@inherits UmbracoViewPage<BlogOverview>
@{
    Layout = "~/Views/Site.cshtml";
}
<h3>This is page number @Model.Page</h3>
<p>The current page's name is @Model.Content.Name</p>

Controller

I haven't explained how this route hijacking actually works. In this example, I'm making a controller with the same name as the document type's alias (BlogOverview). My template name is BlogOverview as well so the ActionResult method in this Controller is also named BlogOverview. In this case the document type alias and the template name are the same but if the template was named BlogPosts then the method would also need to be named BlogPosts.

Note that the Controller class name has to end with the world Controller (as usual with ASP.NET MVC) and inherit from Umbraco's RenderMvcController so that we get access to the current page and current template.

In this example I'll do some very simple processing: using model binding, the querystring value for the page number is set when the request comes in. If there's no querystring (?page=x is missing from the URL) then I'll set the current page number to 1. Remember I rendered the page number in my view earlier.

using System.Web.Mvc;
using Cultiv.Models;
using Umbraco.Web.Mvc;

namespace Cultiv.Controllers
{
    public class BlogOverviewController : RenderMvcController
    {
        public ActionResult BlogOverview(RenderModel model)
        {
            var blogOverviewModel = new BlogOverview(model.Content);

            if (blogOverviewModel.Page == 0) // default value for int
                blogOverviewModel.Page = 1;

            // do paging 

            return CurrentTemplate(blogOverviewModel);
        }
    }
}

For brevity's sake, I've left out the boring paging but as you can see if you go to the homepage of this site then the paging at the bottom actually works. ;-)

I hope this was helpful in showing when route hijacking can come in handy: if you want to do some processing on the server but want to keep your model simple, make sure to consider executing the code in a controller and keep your view very simple (or "dumb" as people like to say).

The full code for the model view and controller are available in a Gist for you to peruse.

Note: Yes, I know I could also have used a SurfaceController with a ChildActionOnly Index method and rendered that from my template but I like exploring and route hijacking was new to me. Works pretty well for my purposes here!

DateFolders were a bit of a hack to make sure that the tree in Umbraco could load quickly. Too many children under one single node would cause the expansion of the tree to slow down. Not only that, it's hard to find items if there's a long list under just one child.

The ListView in Umbraco 7 solves all that, it's a nice sortable, searchable and paged list of child items under the current node. In this screenshot, for example, there's three children under the currently selected node and they're shown in a list on the right side instead of in the tree on the left:

So there were two challanges: moving all items and making sure the old URLs wouldn't start failing. 

Redirecting the old URLs was actually the difficult part (since I suck at regex..). I used IIS' URL Rewrite 2.0 extension for this. This extension is not installed by default on all webservers, but in Umbraco as a Service (which is where this site lives) it is installed, nice!

So now to figure out the pattern: 

• each blog post url starts with blog/
• then a 4 digit year
• then a 1 or 2 digit month
• then a 1 or 2 digit day
• then the blog title

This leads to one group that includes the date and one group that contains the rest of the URL (groups are made by surrounding some arguments in parenthesis):

(blog/\d{4}/\d{1,2}/\d{1,2}\/)(.*)

So once I got that one working, I added it to the web.config, in the rewrite/rules section. So: anything that starts with this regex pattern, do a permanent redirect to https://cultiv.nl/blog/{whatever-was-here-as-"the rest"-of-the-url} (R:2 refers to the second regex group, which is "(.*)" ):

<rule name="Blog" stopProcessing="true">
	<match url="^(blog/\d{4}/\d{1,2}/\d{1,2}\/)(.*)$" />
	<action type="Redirect" url="https://cultiv.nl/blog/{R:2}" />
</rule>

Of course now all my URLs are failing because there's no actual content there, well let's fix that with a super simple UmbracoApiController. 

Each of my blog posts has a content type with the alias of "BlogPost", these all need to be moved under the /blog node which has an Id of 1207. I can go through the descendants of anything under /blog and check the content type to see if it matches. 
I also want to make sure that they're sorted from oldest to newest as that's the default sorting of Umbraco. With that done, I just move all posts directly under /blog. The new API in v6 make this so incredibly easy, awesome:

using System.Linq;
using Umbraco.Core.Models;
using Umbraco.Web.WebApi;

namespace Temporary.Controllers
{
    public class BlogPostsController : UmbracoApiController
    {
        public void PostMovePosts()
        {
            const int blogNodeId = 1207;

            var contentService = Services.ContentService;
            var blogNode = contentService.GetById(blogNodeId);

            foreach (var post in blogNode.Descendants().OrderBy(p => p.CreateDate))
            {
                if (post.ContentType.Alias == "BlogPost")
                {
                    contentService.Move(post, blogNodeId);
                }
            }
        }
    }
}

So: inherit from UmbracoApiController, that will create a route for us to go to: /umbraco/api/{ControllerName}/{MethodName} - So in this case: /umbraco/api/BlogPosts/PostMovePosts

By convention the BlogPostsController needs it's suffix "Controller" stripped off, so that turns in to "BlogPosts" and the method "PostMovePosts" starts with the verb "Post" which translates to the HTTP verb POST. That means I'll be using PostMan with that verb:

And there we have it, everything nicely moved and sorted, ready for the v7 upgrade.

So the first thing I would recommend is: Don’t go home on Friday afternoon. There will be a lot of people going out for drinks and/or food on Friday and this is where you’ll not only talk more about the great stuff you’ve learned, but also a great opportunity to have a lot of fun.

Public transport

If you arrive in the airport, you have two options: the train to Copenhagen central station or the metro to one of the stops in the city center. Google Maps is excellent at telling you where you need to go in public transport, for example this is their advice for getting from the Cabinn hotel to the CodeGarden venue: http://goo.gl/maps/e8Enx. On your smartphone there’s also the option to get directions for public transport, highly recommended.

When you come out of the gate, you walk straight ahead for about 200 meters and you can buy tickets (more on that in a minute) to the right side (either from the machine or at the booths).
If you were to continue walking a little further, there’s an escalator going down on the left side, trains arriving there go to central station. If you want to take the metro however you go straight ahead upstairs and walk another 500 meters or so.

Tickets

I highly recommend getting a Flexcard for zones 1, 2 and 3. That should get you around most of Copenhagen for just 298DKK (ticket is valid for a week). zone 1 is city center, zone 2 is where the CodeGarden venue is and zone 3 is where the airport is.
The other option is to get a “Klippekort” for 3 zones, you can have 10 rides on that one and it costs 200DKK. It’s a bit of a waste though, as you’ll mostly be travelling in zones 1 and 2.

The public transport site http://www.rejseplanen.dk/ has an English option. So it’s easy to plan your trips there ahead of time. They also have apps for smartphones that work great and can also be used in English.

Other transport

Taxi’s are pretty affordable in Copenhagen and they accept credit card payments for all major credit card companies.
If you have your smartphone with you: Click A Taxi is a really nice app for ordering a taxi at the place that you are right that moment. You’ll be waiting for about 5 minutes, most of the time even less.

But to get the full Copenhagen experience you should really rent a bicycle or use the free Copenhagen City Bikes: http://www.visitcopenhagen.com/transport/bike-city-copenhagen

Hotels

I’ll list some of the hotels that are popular:

• https://www.cabinn.com/ - I usually stay here. It’s the cheapest option and they have the ugliest hotels. Rooms are clean and (let’s face it) all you really need is a bed and a warm shower, that’s what they provide (and not much more than that). Cabinn Express and Cabinn Scandinavia are really close to the CG13 venue as well.
• https://www.wakeupcopenhagen.com/ - Also a popular destination for CG attendees, I’ve not stayed there myself, but I hear it’s nice and clean.
• http://www.tivolihotel.dk/ - Next to the WakeUp, it’s more luxurious and includes free ticket to amusement park Tivoli. It’s super nice, but you pay quite a bit more for it.

• Note: Both WakeUp and Tivoli hotel are pretty far away from the metro, so you’ll have to take busses, they’re fine but it’s a bit more difficult to know where you have to get on and off. The drivers are friendly though, ask them to warn you when they arrive at your stop.
• http://www.operahotelcopenhagen.com/ - Opera is nice, it’s in the heart of Copenhagen near Nyhavn, a popular hangout for CodeGarden attendees, and also close to city center.
• http://www.brochner-hotels.dk/hotellerne/kong-arthur/ - Also pretty luxureous and not very cheap. This hotel includes a spa that you can use any time you want.

Internet / 3G

If you’re anything like me, you hate being in a strange city without Google Maps. At all post offices (there is one at Copenhagen central station) you will be able to buy and “Oister 1 uges” SIM card (not sure if they offer micro SIMs now) that you can use for one week. It include 10 gigs of data and it just 99DKK. The only tricky thing is that you need to activate it online. Here’s a guide I put together a few years ago: https://docs.google.com/a/sebastiaanjanssen.nl/document/d/1X-hwfdpjeYGKvS5RbI4W9DOVKWh8HpYjgt1kf7OQLxw/edit

CodeGarden Venue

CodeGarden is held at the beautiful Kedelhallen in the lovely Frederiksberg area of Copenhagen.

At the venue you should expect to get free coffee, tea and water. Lunch is provided and there’s a bar where you can buy snacks and other drinks if you like. Make sure to bring cash for that as not all cards are accepted at the bar.

Dinner is provided on the second day of CodeGarden where you will also be able to join the FAMOUS Umbraco Bingo with fantabulous prizes to be won.

In the neighborhood of the venue there’s also shops and little restaurants where you can have a meal if you want to get away from the nerds (but you will not want to, trust me).

There’s WiFi at the venue that usually works most of the time, but it will be slow and sometimes it just stops working until someone can reset the router. So only count on being able to tweet and definitely don’t expect to download that 20 megabyte Word file your colleague is sending you.

And that brings me to the last point: bring your laptop (there are power outlets you can use), but don’t sit with your laptop open all day. You’ll definitely miss out on the interaction and content of the sessions and that’s just a shame, there’s so many great things going on. Make sure you’re not needed for client work, your colleagues should know you’re at a festival, having a good time and learning loads. Make sure they don’t disturb your experience (as I said, it’s not a regular conference, there’s plenty going on to keep you occupied and learning).

Questions? Make sure to comment! Hope to see you in lovely Copenhagen this summer!

First of all: Umbraco. It has a compiled global.asax out of the box and you can't actually go and extend it. In order to register the routing for the Web API you would normally have to edit the global.asax. Luckily, you can implement this easily using the System.Web.PreApplicationStartMethod.

So in Umbraco I have my Umbraco.Web project which is often completely uncompiled, so it's a Web Site Project instead of a Web Application Project (although I'm changing this). Next to that I usually have a seperate project called CustomerName.Extensions in which I add custom code that is compiled and the DLL ends up in Umbraco's bin folder.

Note: if you want to follow along, ASP.NET MVC 4 should be installed (it includes the Web API) on your machine (not in Umbraco) or you could install the Web API nuget package.

In your (Umbraco) web project, you will also need a reference to Json.NET, again, just install the nuget package.

To start with, I add references to that Extensions project: 

• System.Web
• System.Web.Http
• System.Web.Http.WebHost

Then I add a class to register the API routes on startup, for me it looks like this: 

using System.Linq;
using System.Web.Routing;
using System.Web.Http;
using CustomerName.Extensions;

[assembly: System.Web.PreApplicationStartMethod(typeof(AppStart), "PreStart")]
namespace CustomerName.Extensions
{
public static class AppStart
{
public static void PreStart()
{
RouteTable.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
}

To test if the Web API bits work, add a new item to your project, I don't know about VS2010 but in VS2012 you can just find the Web API Controller Class right there.

If you can't pick that one, then just make a new class and have it inherit from ApiController (as pictured above as well).

The default API Controller will give you some methods and you can immediately compile and check it out.

So in my case, I go to: http://mysite.local/api/values and get a lovely XML feed:

And.. that's all there is to it!

Shannon did a lot of great research last month focussing on just this problem and I'm happy to see that these problems might become obsolete in one of the upcoming versions of Umbraco 5.

From what I've distilled from his blogpost though, there's a very easy way to forces ASP.NET to clear the cache: touch the global.asax instead of the web.config. 

One thing that has bothered me for YEARS now is that I have to go into the web.config, add a space, save, etc. Today I realized that it would be so easy to automate this.

A quick search return a tiny utility called FileTouch that does what it says on the tin: change the modify date (or create date, or access date) of a file.

So I made a tiny little batch file that does just that for me: 

FileTouch .\Umbraco.Web\Global.asax

That's all! I found the temp folder of the site I'm currently working on, executed the above command line and once I try to access the site again I see everything disappearing from the ASP.NET temp folder quickly and new files being put in that equally fast.

You could also make this an afterbuild event in your project but I don't always want the extra hit (rebuilding the cache takes a little extra time), so I prefer to just have the command line open and executing the batch file whenever I think I'll need it.

Foto courtesy of: http://www.flickr.com/photos/emilyrides/5188289325/

What is the ASP.NET Web API? Well, according to Microsoft: "ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework."

When I saw the demo at the TechDays last month, I formulated the following explenation: Anything that returns IEnumerable can now be accessed as XML/JSON and anything IQueryable can be queried with OData syntax; very very easily.

Here's what I had to do to go from a MVC3 site that uses Ninject for dependency injection to a MVC4 site that can answer to Web API calls.

First of all, I had to upgrade my solution to MVC4. The asp.net site provides detailed upgrade instructions that just work.

Next, I installed Web API NuGet package into my existing web project. For some reason, the routing was not updated so in my global.asax.cs I had to add the route like so:

routes.MapHttpRoute("Default API Route",
"api/1.0/{controller}/{id}",
new { id = RouteParameter.Optional });

I think it's pretty self-explanatory that any ApiController I will add can be resolved through the URL /api/1.0/MyControllerName.

In the VS11 tooling (I don't know if this works with VS2010) I can now add a new controller of type API controller. If it doesn't work in VS2010, just create a new controller and inherit from ApiController instead of Controller.

Just running the default code for this worked fine, but of course I wanted to use Web API to access some of my existing database content.

So I added a constructor that accepted a IInfoService class and set up a field for it so it could be injected by Ninject. Well.. *BOOM* that didn't work, error:

The service type provided could not be loaded as a service because it does not have a default (parameter-less) constructor. To fix the problem, add a default constructor to the type, or pass an instance of the type to the host.

Well, after a bit of Googling the answer was provided by Phil Haack: You need to configure a dependency resolver for Web API. To add to the class he posted there, I had to have these usings in place to make it work (make sure to use System.Web.Http.Services instead of System.Web.Mvc): 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http.Services;

Perfect! Or so I thought.. Now when trying to call into the API, something was wrong with the serialization of my object due to the following error:

The type 'MyType' cannot be serialized to JSON because its IsReference setting is 'True'. The JSON format does not support references because there is no standardized format for representing references. To enable serialization, disable the IsReference setting on the type or an appropriate parent class of the type.

Another round of Googling and I found out that the default Microsof serializer does not support my type of object. Problem is, I can't just change my class either. So in comes my favourite Javascript serializer: Json.NET. Another quick NuGet install and then I had to replace the default MS serializer with Json.NET.

The blog post in the last link is actually missing and important piece for me with my Web Application project (it refers to a self-hosted controller, I'm hosting my controllers in my Application!). So, using the JsonFormatter class, I added the following to my global.asax.cs:

// Create Json.Net formatter serializing DateTime using the ISO 8601 format
var serializerSettings = new JsonSerializerSettings();
serializerSettings.Converters.Add(new IsoDateTimeConverter());
var jsonNetFormatter = new JsonNetFormatter(serializerSettings);
var index = GlobalConfiguration.Configuration.Formatters.IndexOf(GlobalConfiguration.Configuration.Formatters.JsonFormatter);
GlobalConfiguration.Configuration.Formatters.RemoveAt(index);
GlobalConfiguration.Configuration.Formatters.Insert(index, jsonNetFormatter);

And there you have it, now when I run the Web API call I get an actual beautiful JSON object back and if you look at the url, I even did some oData querying, because I could! My Get() function returns an IQueryable, from which you get oData querying automatically, awesome!

Of course, if you start with a MVC4 project in the future then most of this will be solved for you. I fully expect Ninject to do some updates so that their NuGet package will just make this work. The only thing that you might need to do is use Json.NET sometimes if you have unsupported objects that can't be changed.

1. Go to cultiv.nl/blog
2. Find the blog post of which I can never remember the title but it has a black icon of a t-shirt with json on it
3. Scroll down to the comments
4. Find the comment by Aaron
5. Copy & paste $(function() { ... });
6. Remove the dots
7. Move the }); to the end of whatever I'm surrounding with document ready
8. CTRL+K, D to reformat the file

Tedious! There's a better way to do this though.

I use ReSharper a lot and it offers a few things to surround a selected piece of code with. Out of the box, in Javascript you can only surround it with {} or (). Nice but not very useful. 

Luckily, you can add your own "surround with" templates:

1. Go to ReSharper > Templates Explorer...
2. Go to the Surround Templates tab
3. Go to Javascript and hit the New Template button
4. Give it a title and edit the template slightly:
   
5. Done!

Now I can just go to my javascript file and select a bit of code, hit the Surround With shortcut (for me CTRL+E,U) and get my new option:

And after hitting return (or "1") my document ready log is properly surrounded:

From now on, I'll be paying more attention to repetitive tasks and constructs I can never seem to remember and making some cool Code Templates where I can.

So, to do this, I created a new template, let's call it "RazorJson" and add a new macro on it:

<umbraco:Macro FileLocation="~/macroScripts/give-me-json.cshtml" runat="server" />

It's important to remember that, in Umbraco, you don't have to create a new page that actually uses this template, if there's no URL conflicts (a node in the root of the site is not called RazorJson), then you can call a template directly. Do note that that context in this case will be the home page (more on that later). 

By going to http://mysite.com/RazorJson I get to see my newly created template, but because it is still empty at the moment I get a blank screen. 

Let's say that I want to output the current node's properties in Json, we can just do something very simple like this:

@{
var node = new umbraco.NodeFactory.Node(Model.Id);
var serializer = new System.Web.Script.Serialization.JavaScriptSerializer();
}

@Html.Raw(serializer.Serialize(node.Properties))

So we're taking the current node's Id (Model.Id) and instantiate a new Node() from it. Then it's properties gets serialized into a Json string and that is what's being shown on the page. 

Presto!

Now, to make it a bit more interesting, remember how I said this page would only run in the home page's context? You could just turn any of your pages into a Json object by going to, for example, http://mysite.com/about?altTemplate=RazorJson
This will render the "about" page with the RazorJson template and therefore output all of the "about" page's properties in Json notation.

I tweeted about this and got some comments, among which this one:

Gareth is right, to create a /base extension, you write a seperate class that handles your businesslogic for you and /base just outputs either XML or a string.

However, I think using a template with a Razor script on it seems a bit more powerful. As I've shown above, it's easy to work within the context of a page using  altTemplates, but you can also still write any old class that returns a string (or XML) and call that from Razor. In fact, I could just call my existing /base extension from the Razor file because, as you should know, from Razor you can access any old class in your solution. 

What I do see happening is that people will write @functions in Razor and never extract them into a seperate method. This is great for quick prototyping and if you really are never going to use those functions again, it's no problem. But it does make it a bit easier to start ignoring seperation of concerns and the DRY (don't repeat yourself) rule and just start copying functions from one Razor script into the other.

All I can say is: with great power comes great responsibility. If you want to be able to change your code in few months, make sure to refactor early and refactor often (#47).

Sorry XP users, this is written for Windows 7 (you really need to update your 11 year old OS, really). Also, please remember that there's a thousand different computer configurations out there, so this might not be entirely accurate for your specific computer.

So here's a step-by-step guide. This is most certainly not the easiest way of installing Umbraco, but it gives you and overview of how you can do it completely manually, without tools like the Web Platform Installer or Webmatrix.

Let's get started:

1. Download the latest Umbraco release (choose the umbraco binaries, please don't try to install from the source, if you're a new user you really don't need to touch the source for months at least)
    
2. Unzip the files into the directory in which you want to install Umbraco. In this example I will do it in: D:\Dev\MyNewUmbracoSite
   Note: Before you unzip the umbraco binaries, right-click the zip file and choose "Properties", then hit the "Unblock" button to make sure none of the dll's will be blocked. I use 7zip in which you don't have to do this.
    
3. Here we're going to do ourselves a huge favor by not installing Umbraco in a virtual directory. 
   In my hosts file, I now add a new domain name, that I want to use for my site, in my case: mynewumbracosite.local
   The hosts file can be found in: C:\Windows\System32\drivers\etc
   Make sure that the current windows user has permissions to the hosts file, as of Windows 7 this file is not writable by default.
   
   
   Add the entry:
   127.0.0.1      mynewumbracosite.local
   
   
   When that is done, the site can be created in IIS.
4. Start your IIS Manager and right click on "Sites" and choose "Add web site". 
5. The site name will be MyNewUmbracoSite, the Physical path will be D:\Dev\MyNewUmbracoSite and the Host name is: mynewumbracosite.local
   The application pool should be changed to use the ASP.NET v4.0 app pool. 
   Note: the application pool should be configured to use integrated pipeline mode (this is the default for the ASP.NET v.4.0 app pool).
    
6. Next, you should set some permissions so that IIS is able to execute the pages in your site, right-click on the MyNewUmbracoSite folder in D:\Dev, choose Properties and go to Security. Then click the Edit button and the Add button. Find the IIS_IUSRS account and give is Full Control permissions.
   
   Make sure to read  more information about setting permissions as just giving full control everywhere is not best practice.
7. Alright, almost ready to start the install process, go into your SQL Server management studio and create a new database (for example: mynewumbracosite).
   
8. In the Security\Logins section of Management Studio, create a new user (SQL Server authentication, remember to uncheck "Enforce password policy").
   
   
   Remember the credentials, mine will be umbraco / password
9. Go back into your database and go to Security\Users. 
   
   Enter the username umbraco in both user name and login name fields. Enter dbo in the default schema field and make the user db_owner for schemas and roles.
   
10. Now you can go to http://mynewumbracosite.local/ and you should be presented with the setup screen.
11. Go through the wizard and when asked for a database, choose "I already have a blank SQL Server or MySQL database" and then "Microsoft SQL Server".
12. Enter the server name, database name and credential that you just made and click "Install".
    
13. As prompted by the installer, create a new user for your umbraco login.
    
14. For the next step in the install wizard, if you want install a starter kit do so, if not choose not to.
15. When you hit next, you're done.

Please leave a comment when there's something unclear. If you follow along and do things exactly like in this guide, you should be good to go.

This is not what you want, it's labor intensive, prone to mistakes and there's no way to do any kind of continuous integration. The kind people at Vega IT Sourcing must have felt the same way and developed a solution for this called uSiteBuilder. 

The setup that I've chosen for this is a little bit different from the default that you get when out of the box. I've just downloaded and built the source of uSiteBuilder and from the "Vega.USiteBuilder\bin\Debug" folder I took the Vega.USiteBuilder.dll to use in my project.

My default Umbraco solution looks a bit like this:

More on how I set this up can be found in the Easily debug your custom Umbraco user controls in Visual Studio blog post. I still use that setup, except now in VS2010 and I only have 2 projects in there: the Umbraco site and my custom code organized in folders.

I reference the uSiteBuilder dll in the "SomeCompany.Extensions" project and then I'm ready to get started.

My post-build events look like this by the way:

XCOPY "$(ProjectDir)bin\SomeCompany.*" "$(ProjectDir)..\Umbraco\bin\" /y

XCOPY "$(ProjectDir)UserControls\*.ascx" "$(ProjectDir)..\Umbraco\UserControls\" /y

XCOPY "$(ProjectDir)Masterpages\*.master" "$(ProjectDir)..\Umbraco\masterpages\" /d /y

I really don't want to build my project every time I make a change to a masterpage file, I change my masterpages in the Umbraco site, not in the Extensions project. So for masterpages, I've added the extra /d parameter that will make sure only files that are newer in the Extensions project get copied to the website.

Master pages

Let's start with setting up a master page for the site, called Main, and a nested master page for the content of my TextPages.

Just right click in the Masterpages folder in the "SomeCompany.Extensions" project and create a new Masterpage called Main. The one thing we're going to change for now is setting the MasterPageFile to Umbraco's default MasterPage.

<%@ Master Language="C#" AutoEventWireup="true"

CodeBehind="Main.master.cs"

Inherits="SomeCompany.Extensions.MasterPages.Main"

MasterPageFile="~/umbraco/masterpages/default.master" %>

We'll get back to this Masterpage later.

Document Types

The most important feature of uSiteBuilder is that you can create your document types in code, instead of through the Umbraco interface. You just build a dll and drop it in your site's /bin folder. Once you do, the document type definitions that you've made get updated in Umbraco's database and, presto, no more manual deployments for document types!

As you might have read, I set up all of my sites using a SiteSettings node first and everything else goes under that. My goal is to get a document type structure that looks like this:

So let's get started with some code in DocumentTypes\SiteSettings.cs:

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Site Settings", IconUrl = "house.png", Thumbnail = "developer.png", AllowedChildNodeTypes = new[] { typeof(TextPage) })]

public class SiteSettings : DocumentTypeBase

{

[DocumentTypeProperty(UmbracoPropertyType.ContentPicker, Name = "Homepage", Tab = "Settings", Description = "The item that you pick here will be the homepage of your site.")]

public string umbracoInternalRedirectId { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.TextboxMultiple, Name = "Google Analytics Code", Tab = "Settings", Description = "Paste your Google Analytics code here to get statistics of your website")]

public string googleAnalyticsCode { get; set; }

}

}

Make sure to go through the uSiteBuilder tutorials if you're not sure what's actually going on here.

Great, that's that sorted, we can continue to the PageSettings document type:

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Page Settings", IconUrl = "folder.gif", Thumbnail = "folder.png", AllowedChildNodeTypes = new[] { typeof(TextPage) })]

public class PageSettings : DocumentTypeBase

{

[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Page title", Tab = "Page settings")]

public string pageTitle { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Meta title", Tab = "Page settings")]

public string metaTitle { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Meta description", Tab = "Page settings")]

public string metaDescription { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.TrueFalse, Name = "Hide in navigation?", Tab = "Navigation")]

public string umbracoNaviHide { get; set; }

}

}

The PageSettings document type is just a set of generic properties that I am going to need on all of my publishable content pages. I would generally also add checkboxes for "Hide in sitemap", "Show in main menu", "Show in footer menu", etcetera.

I've cheated a little bit here, as you can see, I am allowing documents of type "TextPage" under the SiteSettings, but we haven't actually defined the TextPage yet. We'll fix that right now: 

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Text page", IconUrl = "page.png", Thumbnail = "docWithImage.png", AllowedTemplates = new [] { "TextPage" }, DefaultTemplate = typeof (TextPage))]

public class TextPage : PageSettings

{

[DocumentTypeProperty(UmbracoPropertyType.RichtextEditor, Name = "Content", Tab = "Content", Description = "")]

public string bodyText { get; set; }

}

}

I am inheriting from the PageSettings class that I've just created so that TextPage will be nested under it.

Also, I have set the AllowedTemplates to TextPage, which doesn't exist yet. So it can now be created.

I've created a ContentPlaceHolder in Main.master:

<asp:ContentPlaceHolder Id="body" runat="server"></asp:ContentPlaceHolder>

Now I need to create the TextPage Masterpage by adding a new nested masterpage, based on Main.master:

We could just copy both masterpages (Main & TextPage) over to the site, but it will not do anything as we haven't told uSiteBuilder to pick it up and create the templates in Umbraco. 

So, as promised, we're getting back to Main.master. Go into the codebehind and change it to inherit from SiteSettings, like so:

public partial class Main : Vega.USiteBuilder.TemplateBase<DocumentTypes.SiteSettings>

A similar inherit is necessary for TextPage, but it will be from the TextPage document type. This will make sure that the docType knows how to find the template that it is allowed to use:

public partial class TextPage : Vega.USiteBuilder.TemplateBase<DocumentTypes.TextPage>

What can we not do?

There has been a lot of good news in this article so far. It's easy to create document types and templates and I haven't covered this, but it's also very easy to create UserControl macros from uSiteBuilder.

But uSiteBuilder is still incomplete at the moment. There's no way to create XSLT macros and you cannot predefine the sorting of tabs on your document types (although you can just sort them manually in Umbraco's interface, that works just fine). Furthermore, there's no way to create media types either.

As this is an open source project, I have good hopes that someone will create the missing bits as they need them. For now, I've been able to work around them really well though.

That being said, it only took me about an hour or to get started with it and even if I would still need to do some things manually, I can still gain a lot in productivity for the supported features, which is fantastic!

Putting it all together

This is a completely reusable way of creating your site structure. In your next project you can just start out with these basic document types and templates and build them out as needed.

Another nice advantage of having your document types as classes is that it's so easy to open them up and find the exact alias of a property to use in our Razor scripts, no more going to "Settings" > expanding "Document types" > going to the "Generic properties" tab and finding the alias.

Finally, as an added bonus, using Razor is really what makes it able for me to work with uSiteBuilder without problems, as you can create Razor macro's without.. creating a macro.

That's right, it's as easy as referring to a file. In your template, just insert a macro like this:

<umbraco:Macro FileLocation="~/macroScripts/MainMenu.cshtml" runat="server" />

So, now when you deploy your site, all you need to do is move around the changed files. Don't forget the "SomeCompany.Extensions.dll", together with "Vega.USiteBuilder.dll" it will start creating and modifying your docTypes and templates. 

Thanks to the great folks at Vega IT Sourcing for a truely awesome tool that makes my life much easier, I love it!

Disclaimer: The Razor  implementation is still very new and changing rapidly, some of this information might already be outdated.

Paging is also something that can be made really generic, making it nicely reusable for any page.

There is two parts to the paging solution, a normal C# class (but in the App_Code folder, so no compilation required!) that takes the amount of items and the items that should be displayed per page and then does some calculations based on the "page" querystring (come to think of it, I should've actually made that an input variable as well).

I admit that this is a bit verbose and I don't actually need some of these fields, but it's nice to have them in case I need to do something wild with them later.

using System;

using System.Web;



public class Paging

{

public int ItemsPerPage { get; set; }

public int CurrentPage { get; set; }

public int PreviousPage { get; set; }

public int NextPage { get; set; }

public double TotalPages { get; set; }

public int Skip { get; set; }

public int Take { get; set; }



public static Paging GetPages(int itemCount, int itemsPerPage)

{

int page;

int.TryParse(HttpContext.Current.Request.QueryString["page"], out page);

if (page == 0) page = 1;



var pages = new Paging { ItemsPerPage = itemsPerPage, CurrentPage = page, PreviousPage = page - 1, NextPage = page + 1, TotalPages = Math.Ceiling(itemCount / (Double)itemsPerPage), Skip = (page*itemsPerPage) - itemsPerPage, Take = itemsPerPage };


return pages;

}

}

Then, I needed a really basic way to show the paging. I wanted just some links for the different pages and a "previous" and "next" link. Also, the "current" page shouldn't be clickable. So we bring out a Razor helper (also in the App_Code folder) that can be reused and potentially modified when needed.

@using umbraco;



@helper RenderPaging(Paging paging, int currentId) {

if (paging.CurrentPage > 1)

{

<a href="@library.NiceUrl(currentId)?page=@paging.PreviousPage">< Vorige</a>

}



for (var i = 1; i <= paging.TotalPages; i++)

{

if (paging.CurrentPage == i)

{

@i<text>&nbsp;</text>

}

else

{

<a href="@library.NiceUrl(currentId)?page=@i">@i</a><text>&nbsp;</text>

}

}



if (paging.CurrentPage < paging.TotalPages)

{

<a href="@library.NiceUrl(currentId)?page=@paging.NextPage">Volgende ></a>

}

}

That's all, so now in my overviewpage, I initilialize the paging object and select the records that I want to show for the current page. Note that Skip() and Take() have been added to my Linq query so that I only get the 10 articles that I want.

@{
var paging = Paging.GetPages(allArticles.Count(), 10); 

var selectedArticles = allArticles.OrderByDescending(x => x.CreateDate).Skip(paging.Skip).Take(paging.Take).ToList();
}

<div class="articleList">

<ul>

@foreach(var article in selectedArticles) {

<li>@article.NodeName</li>

}

</ul>

And finally, to render the paging, it's a matter of calling the helper, note that the namespace is once again the name of the .cshtml file (as in the functions in the previous post).

<div class="paging">

@PagingTemplate.RenderPaging(paging, Current.Id)

</div>

There you go, from 100+ lines of unreadable XSLT to about 60 lines of nice, clean and easily reusable paging in Razor. What's not to love?

Ps. I still love XSLT, really I do. :-)

Disclaimer: The Razor  implementation is still very new and changing rapidly, some of this information might already be outdated.

When using the Razor view engine it's important to remember that you are just writing HTML and, when you need some data, you switch context by starting with the "@" sign and adding some C# (yes, you can also make .vbhtml files and start writing VB, if you must):

<article>

<header><h2>@Model.Name</h2></header>

<img src="@Model.ImageUpload" alt="@Model.Name" />

@(Html.Raw(Model.BodyText))

</article>

In umbraco's case, the "Current" object holds the same data as the "currentPage" variable does in XSLT. All of the properties that are on the current document type are available to you, although you only get intellisense with the default properties (Id, Name, CreateDate, etc.).

As you can see, there's an interesting mix of html and @ signs. Not much to explain here except for the Html.Raw call, this is the same as saying disable-output-escaping="true" in XSLT. If you don't do this, all of the text will be encoded as HTML entities.

Now we have pretty decent looking page, let's make it a little more complex. Say I have a few news articles somewhere in my site, the titles of which I would like to display in a sidebar at all times. I could go and look for those nodes by looking at the Model.Parent and up and up until I was at level 1 and then find the child node with the "Article" type, but that's quite a bit of work to do every time I need to do something similar*.

It was much easier just to use Linq 2 Umbraco and query Umbraco's cached content (I'm open to suggestions if there's a better way).

* Although UQL will make this a bit easier

So now I get a Razor template that looks like this:

@using System;

@using System.Linq;

@using umbraco;



@{

var context = new MyNamespace.MyModelDataContext();

var catArticles = context.Articles.OrderByDescending(x => x.CreateDate).ToList();

}

<article>

<header><h2>@Model.Name</h2></header>

<img src="@Model.ImageUpload" alt="@Model.Name" />

@(Html.Raw(Model.BodyText))

</article>

<aside>

<ul>

@foreach (var article in catArticles)

{

<li>

<a href="@library.NiceUrl(article.Id)">@article.NodeName</a>

<li>

}

</ul>

</aside>

Still pretty easy, now it's time for a real challenge. I have an image upload field and an image cropper on the article pages. The image cropper stores bits of XML for the values of the different crops. So just doing a @article.ImageCrop won't work. Here's where helpers come in.
Helpers can be created inline, but it's better when you just create a new .cshtml file in your App_Code and refer to that helper. It becomes reusable and actually helps you write better modular code. In this case the helper will return a value so it's called a function.

Careful here: if you add a .cshtml file to the App_Code folder through the Visual Studio interface, it will also add a key in the web.config:

<add key="webpages:Enabled" value="true" />

This wil result in a "yellow screen of death", complaining that the UmbracoMembershipProvider is configured incorrectly: "Parser Error Message: This method cannot be called during the application's pre-start initialization stage."

So I've created a tiny little XML parser (untested in the real world, be sure to rename from .txt to .cshtml) and will use that to get the cropped image out:

<aside>

<ul>

@foreach (var article in catArticles)

{

<li>

<a href="@library.NiceUrl(article.Id)">

<img src="@XmlFunctions.GetAttributeValue(article.ImageCrop), "/crops/crop[@name = 'Small']", "url")" alt="@article.NodeName" />

</a>

<li>

}

</ul>

</aside>

Note that the namespace of the helper is the filename I've created in the App_Code folder, so XmlFunctions.cshtml translates to the XmlFunctions namespace in the Razor template.

And that concludes the first part of a few Razor posts.

For more info, be sure to check out these links:

• http://www.aaron-powell.com/umbraco-4-and-razor
• http://www.asp.net/webmatrix/tutorials/2-introduction-to-asp-net-web-programming-using-the-razor-syntax
• http://weblogs.asp.net/scottgu/archive/2010/07/02/introducing-razor.aspx
• http://joeriks.wordpress.com/2011/01/12/razor-inline-helpers-in-umbraco-juno-full-sitemap-sample/
• http://joeriks.wordpress.com/2011/01/04/playing-with-razor-in-umbraco-an-old-skool-contact-form/
• http://haacked.com/archive/2011/01/06/razor-syntax-quick-reference.aspx

Last Friday I was skyping with my friend Yannick and he was having a little trouble with redirecting the home node of his site and using my search engine sitemap package. After some back and forth we eventually came to the ultimate setup.

Basically, there will always be two nodes: "Site settings" and "Home". The settings node is there so a few site-specific settings (like the Google Analytics account) can be stored. It also helps preventing editors from being able to create documents of just any type. By default, under the "Content" node you can create nodes of all kinds and generally, you want to very much limit what they can create to prevent the site from becoming a mess.

You can see an example of this structure in the following image:

The "Site" node has the hostname(s) of the site set to it, although it doesn't have to have that. Umbraco will present the first node that it finds in the content tree as the homepage of the site.

I've redirected the "Site" node to the "Home" node so that the correct page will be shown to people entering the site. Later on in the development of your site, I'll be using Umbraco's NiceUrl method to point to pages in my site. Some of those NiceUrl calls go to the "Home" page. This will currently point to "/home".

If you've setup your site to redirect using the umbracoRedirect property, you will have created a 302 redirect from "/" to "/home". This is not what you want for two reasons:

1. search engines don't like that there are two pages in the site with the exact same content
2. search engines know that a 302 redirect means that it's temporary, so they will keep expecting that the "/" and the "/home" pages are supposed to be different

Additionally, you will be faced with another, more immediate couple of problems in Umbraco:

1. the altTemplate mechanism controlled by the 404handlers.config gets confused and only works if you prefix the template name with "/home", which would cause a problem with the search engine sitemap package that I mentioned earlier
2. you are suddenly unable to save XSLT files from the built-in editor in Umbraco

This is easily fixed though. On the "Site" node, I've put a property of the Content Picker type with the alias of umbracoInternalRedirectId that will not actually do a redirect, but will render whatever node you pick instead of the current node. Logically, I have picked the "Home" node.

This leaves you with a bit of a problem still, as Umbraco's NiceUrl method still produces links to "/home". To solve this, you can just do a simple urlRewrite and make the "/home" call always do a 301 (permanently moved) redirect to "/". Just the way search engines like it. Be careful: this will cause an infinite loop if you do it while the umbracoRedirect property is still on there, only do this with the umbracoInternalRedirectId property.

The urlRewrite config looks like this (note the "$" at the end of "home" is there to make sure that if you want any nodes under your home page, they won't be rewritten as well):

<add name="home"

virtualUrl= "^~/home$"

rewriteUrlParameter="ExcludeFromClientQueryString"

destinationUrl="~/"

ignoreCase="true"

redirect="Application"

redirectMode="Permanent" />

And there you have it, the "ultimate" site structure for you to start your site with. Google is happy, Umbraco is happy (it will save your XSLT files again), everybody is happy!

That being said, this will probably be my last blog post for this year. Happy holidays and see you next year.

But.. Styling forms is really hard! You have to hack a lot of CSS to make a moderately sexy looking form.

I am not a frontend developer so this usually ends badly. In fact, up until now, I've not used Contour for a lot of sites because the form styling was so difficult to do. For example, how would you do something a little different looking, like this:

This is all changing. I recently released the RestContour package, that lets you post from any form into Contour. Currently I'm working on making this very very easy to use, and make it look sexy in the process. I've used the RestContour package for an upcoming website and have made it even better. Now you can just use any old HTML form easily and make it into a Contour form, validation and all, with very little effort.

Check out the video below:

You can download this version of the RestContour package from the project page (RestContourPreview_0.8.0.zip) and the source (Cultiv.RestContour.7z) is also available.

Not a problem. I'll be showing you an example using "/base", Json.NET and a little bit of what I'm doing with Contour at the moment.

/base
Umbraco's "/base" is an extendable system for creating raw feeds directly from Umbraco using very basic Url's. These feeds are typically in XML format but it's very easy to create a JSON feed instead of an XML one. The way /base works is by mapping a method to a URL through a config file (see the above link for an introduction).

JSON
In javascript you can use JSON (JavaScript Object Notation) to access data. A JSON object is just an array of strings, like so:

"person": {

"name": "Sebastiaan Janssen", 

"country": "The Netherlands"

}

You can access the information in this object by evaluating this string in javascript. Let's say the above JSON string was in a variable called "json":

var result = eval("(" + json + ")");

var name = result.person[0].name;

The variable "name" will now be filled with the string "Sebastiaan Janssen". To make sure the evaluation will work, you need to surround the JSON string with braces, which is what I've done on the first line.

Json.NET
So how great would it be if you could just output any old .net class as a JSON string, so you could easily use it in javascript? With Json.NET you can do just that! Have a look at a simple example in the source of my RESTContour package. The GetJsonForObject method accepts any object and spits out a JSON string, great!

Putting it all together
So let's combine all of the above. Create a method that outputs a string, the string will contain some JSON. Normally, a call to a /base method will result in some XML output, but we want a string.

In the restExtensions.config file there's a "permission" node, add a new attribute returnXml="false" to it so that the output will just be a string.

Now we can make an AJAX call (using a little jQuery) to the /base URL and evaluate the result. Going back to the RESTContour example class mentioned above, I am going to get all of the available Contour forms and alert the form names.

$(document).ready(function () {
var getFormUrl = "/base/getContourForm/GetAllForms";

$.ajax({
url: getFormUrl,
success: function (data) {
var result = eval("(" + data + ")");

for (var i = 0; i < result.length; i++) {
alert(result[i].Name);
}
}
});
});

As said, you can output just about any object as a JSON string using base, which can be very useful, try it out!

I've since polished the code a little bit and it is now available to download from the projects section at our.umbraco.org.

Of course I expect to get as many votes on Our Umbraco as during the package contest (you rock)!

The PhotoMetaData package will extract meta data from images that you upload in your media section. This works in both Umbraco 4.0.x and 4.5.

When you create a property with the correct name it will be filled as soon as you upload an image in the media section.

Here a video with a quick overview of the package.

Photo by the wonderful Douglas Robar

By giving you a score from 0 to 100, you can easily compare your site to others. The score is divided up in dozens of different indicators that all have a certain weight in the calculation of the score. All of the indicators are nicely explained to help you understand why they're there (and if you should care about them).

My site actually scored pretty well (56 at the time). Of course I don't have an entry in wikipedia and my Alexa rank really sucks, so no points there. Fair enough.

I found that I could easily improve my score by tweaking some things in my site, mostly using content that I already had available anyway. Umbraco makes this really, really easy. No programming needed, mostly tweaks to my templates / XSLT files. Here's what I did (and what anybody could do!).

Sitemap

Of course I already have a sitemap on my site thanks to my own fantastically simple sitemap package (it's just a bit of XSLT, really, have you voted yet?).

However, woorank told me that a sitemap was missing. Of course, I have no link to the sitemap anywhere and it's not called sitemap.xml. So I thought I'd find out how to let search engines (and woorank) know that I have one available to crawl.

First of all, you can include a meta tag in the head of your HTML. Easy enough, just add it to the template, but this won't always work. Google, for example, relies on the sitemap being in your robots.txt file. Unfortunately, the robots.txt can't be edited from within Umbraco, so I had to make this improvement by updating it manually.

Microformats

Jeff Atwood of Coding Horror and StackOverflow fame wrote a blog post in December about making crappy HTML even more crappy by putting extra crappy HTML in it to support microformats. In the end though, he concludes that it's too easy not to do.

I don't really see the added value at the moment, but it can't hurt to implement some of it.

The only microformat that I could think of would make sense on my site was the contact information, using the hCard format. So off I went, added some div's and spans in my footer XSLT and in the HTML on the contact page.

Dublin Core

What's this you ask? I had no idea either. As it turns out Dublin Core meta data is very structured information about the page you're currently on. Although, it seems only slightly better than the normal meta description / keywords tag.

As with the microformats, it doesn't hurt, so I spent 5 minutes updating my main template to include Dublin Core data (title, description, creator & publisher). This data was easily accessible from Umbraco and I'd already used most of it in the other meta tags, so a quick copy & paste in the template did the trick.

Geo Meta Tags

Oh boy, even more meta tags. Alright, geographic information. The content of my site isn't targeted at a specific geographic location, nor does it show any data that belongs to a location. I suppose it's nice to know that I'm in The Hague. Once again, too easy not to do, so I added the placename, region and coordinates to the template.

Conclusion

There is a lot of meta data out there. And apparently, search engines actually look for that information. I do get the impression, though, that there is too many different formats. Can we just pick one and stick with it? Oh wait, it's the web, when has that ever happened?

It took me a few hours to figure out what information was needed everywhere, but once I did, Umbraco made it painless for me to update my entire site using existing data.

This will be even more fun when I start adding the geo information to the site I'm currently working on that shows panorama pictures. Each picture already has GPS coordinates so it'll be a really quick XSLT addition.

I love working with the latest and greatest though, so in a few spare hours just now I have been plotting and scheming and came up with a brilliant solution to thwart the command of my opresser, muhahaha!

Yes, I did it, I created a tool that can convert my complete VS2010 project back to a VS2008 project so that I can commit my code without my opponent knowing worked in VS2010.

This is done, very simply by replacing a few strings in the .sln and .csproj files. Now, this is a simple approach and it will throw away some information that is new to VS2010. However, it works for my purposes and I'm sharing it here so that people will be able to build upon it if they wish, or use it as is.

Mind you, there is NO GUARANTEES and I'm sure this is going to kill your project if you're not careful!

Was that proper warning? Okay, well here it is: two old-school batch files and a tool to do the string replacements (which I got from programmersheaven).

You can now download the fully automated VS2008 to VS2010 converter, enjoy.

Oh HAI Gerben, didn't know you were going to read this...

When opening a node of this document type (in Umbraco's Content area, not the document type editor), I get the following (rather generic) error:

I must add that while creating some new properties on this document type, the property was added, but I did get and SQL time-out. Not sure why that was, but it must have interupted an update process on existing nodes.

This is probably the reason that the current nodes are now corrupt. As you can see in the exception, there was a problem adding a control to the page.

The solution is easy, you have to publish all of the nodes and its subpages to fix the error. Voliá!

Richard Soeteman adds some extra information on a similar error while deleting a property on a document type. The issues could be related, so if you still have problems, check out his blog post as well.

I'm not asking for votes, I'm proud to be listed among giants and you can make your own decisions.

However, I would like to promote the others on the list:

Chris Houston was the first one to reply on my first blog post and I love how active and involved he is in the community. I can't wait to see the cmsMailer package that he's involved in. Vote for Chris!

Chris Koiak has made some cool packages and seems to be a great developer with a passion for Umbraco. Besides, he's from Glasgow, he must have a great accent. Vote for Chris (no, not the other one, this one)!

Dan Drayne must have a very high accept rate on our.umbraco, his forum replies are always very helpful. Vote for Dan!

Darren Ferguson's source code makes me jealous! Awesome packages, I have a lot to learn from this guy. Vote for Darren!

Dirk De Grave is always helpful on the forum, always there (does he ever leave his computer?), patient beyond belief even though some people test his patience sometimes. Vote for Dirk!

Douglas Robar really is the best teacher I've ever met. His posts on the forum are long and complete, with amazing attention to detail. Vote for Douglas!

Jan Skovgaard also always seem to be online, helping out, asking questions. Plus he seems to like Dutch people, perfect! Vote for Jan!

Jesper Ordrup seems to be taking Umbraco to new heights with the projects he's involved in. Let's hope he keeps sharing his insights. Vote for Jesper!

Lee Kelleher is a busy bee, he seems to be everywhere at the same time and should be rewarded for all of his efforts in the community. Vote for Lee!

Lee Messenger's ideas to change the our.umbraco forum from "just" questions and answer to even more thought provoking conversations are great, keep up the good work. Vote for Lee (THIS one)!

Morten Bock: uForum, need I say more? Awesome coder. Vote for Morten!

Nik Wahlberg I don't know so well unfortunately, but he must be awesome 'cause he's wearing sunglasses, just like Niels. Vote for Nik!

Peter Dijksterhuis should win because he works on a farm one month a year. Also, he made the great calendar package, good stuff. Vote for Peter!

Petr Snobelt thumbs up for the MemberControls package, and his avatar. Vote for Petr!

Richard Soeteman is the number one Umbraco fanboy from The Netherlands. This guy might be singlehandedly responsible for the rise in popularity of Umbraco in the last year or so.. ;) Vote for Richard!

Ron Brouwer another fellow Dutchie and a very helpful guy, love his work. Vote for Ron!

Thomas Höhler must be the loneliest Umbracian in Germany, but that's great, gives him time to help everybody out on the forum and on Twitter. Also makes cool packages. Vote for Thomas!

Tim Saunders always helpful with a different take things, I love seeing alternate solutions. Vote for Tim!

Warren Buckley well, what's not to love about this guy, CWS is awesome, he's always looking to add value to the community, and it's working. Vote for Warren!

... I really can't choose, I might as well vote for myself now!

Of course, this is all a clever ploy to get everybody to vote for me anyway.. I trust you will all not find me out. ;-)

It's just a quick run through of how I create a new Umbraco installs on my dev machines. It's easy!

I noticed after the recording that I didn't change the path for the database files. During the creation of the new database, you can easily change the path of where the database files are stored here (buttons marked yellow):

I tend to mumble a little, I'll work on that for future screencasts (also, I didn't shave, sorry). ;-)

Hopefully this will help some people setting up their Umbraco install manually.

I've been hosting some projects on Unfuddle for a while now, but have not been very happy with fiddling with SSH keys and setting up the central repositories through the Git Extensions for Windows. It works, but that's all I can say.

Another issue I was not looking forward to tackling was setting up TeamCity to pull from Unfuddle. I haven't tried, and for all I know it might work great, but if there's a perfectly good shortcut that I can take, I'll take it!

A few days ago I saw some tweets from people mentioning Git and DropBox as a combo. Unfortunately, I can't find the messages any more as Twitter's retention policy seems to be very aggressive. So I decided to try doing it myself.

The advantages of having a Git repository in DropBox are that:

• it does not rely on a service that (for all I know) might go out of business one day;
• it prevents me from having to create SSH keys as credentials;
• it makes it easier to point TeamCity to a central git repository (which is in fact on the local disk);
• the central repository is always synced to all of my dev machines and to the DropBox server, so there is multiple backups in case of catastrophic failure;
• you will always have the ability to push changes to a central repository, even if you have no (or intermittent) internet connectivity;
• if you have to work without internet connectivity, but with network connectivity, you could just set-up a network share and push and pull to each of the repositories that way.

I'm wildly enthusiastic about the distributed nature of the Git version control system, it really does allow me to work from anywhere and in any way that I want.

Setting up Git with DropBox on Windows

I am assuming that you have DropBox installed and that you are using the Git Extensions that I've mentioned in earlier blog posts on Git.

I've created a folder somewhere in my DropBox folders that will hold my Git repositories. In there, I've created a folder called "Example.git".

Next, I created a new Git repository using the Git Extensions. When you start Git Extensions, choose "Initialize new repository" from the "Commands" menu.

I created a "Central repository, no working dir" in the "Example.git" folder.

Then, in the folder that holds my Example project, I created a personal repository, as I would do normally when putting you project under version control (again through "Commands", "Initialize new repository").

This will open up the repository in Git Extensions. The first thing I like to do is hit the "Edit .gitignore" button, add the default ignores and commit that as the initial commit.

With that inital commit out of the way, I will add a remote from the "Remotes" menu.

I've name the new remote "DropBoxExample" and instead of entering a URL, I point to the "Examples.git" folder that I created earlier.

After clicking the "Save" button, Git Extensions will ask if I want to automatically configure the default push and pull behavior, I've skipped this step because the folder on the disk is not actually a server that understands commands. Then I closed the "Remote repositories" window and start pushing the master branch to the remote.

And got a confirmation message, it worked!

Now I am able to actually set the pull defaults, so I go back to managing the remote, go to the "Default pull behavior" tab to choose the defaults from the dropdown lists and clicked "Save".

All done!

I went to my other machine and created the same "D:\Dev\Example" folder.

I opened up Git extensions and initalized the folder as a personal repository. Then I was able to add the remote repository in exactly the same way, instead of entering a URL, I pointed to the "Example.git" folder in DropBox, saved the remote and pulled from it.

To my delight, I saw the .gitignore file appear immediately and noticed that I had received the commit history from the other machine. Success!

Of course I then proceeded to add a Visual Studio project, pushed it to the central repository, pulled it in on the other machine, and again, everything appeared as I hoped it would. Success!

I believe my hosting provider makes a backup of the whole server every night, and at best, I can have them restore a 1-day old backup. One day of retention is not something that I feel comfortable to rely on, by far!

Recently Jeff Attwood (of Coding Horror and StackOverflow fame) had a big scare and the resulting discussion that followed, lead to a blog post by Joel Spolsky (of FogCreek and StackOverflow fame) pointing out that backing up is not the problem, restoring usually is.

Well, since I had NO backup strategy, whatsoever, I figured it was about time to change that.

My current server specs are: A Windows Server Web - (2008 Hyper-V VPS) with IIS7 and Microsoft SQL Express server. It's that simple!

What to backup?

The question of what to backup seems like a simple one to me:

• my websites (including file/folder permissions);
• the website's MS SQL databases;
• the IIS configuration for the websites;
• the IIS log files, so that I could maybe reconstruct what happened in case of a catastrophe.

How to backup?

Websites and meta content

The websites are all in one folder, so that's easy (I'll talk about the permissions later).

I had to look a little bit to find a way to backup the configuration files, but a post about IIS configuration history was a great resource.

To backup the current IIS configuration, I included the %windir%\system32\inetsrv\config\ folder and I love that the configuration changes are being written automatically to the %systemdrive%\inetpub\history directory. That way, I could recover and older configuration if needed, cool!

Finally, I included the %systemdrive%\inetpub\logs file for the sake of it.

SQL Express

At first, I was backing up SQL's ".mdf" and ".ldf" files, which is an utterly stupid idea, as I learned from StackOverflow postcast 78. So I needed a different strategy for that. SQL Express doesn't offer the ability to create automated back-ups, so I had to look for extra software. This was difficult, nothing really did what I wanted it to do: give me a bunch of .bak files. Everything I found was either too fancy or didn't work.

My colleague pointed me in the direction of an article on ServerFault and I was able to construct a decent enough solution out of this.

I took the SQL script in the ServerFault post and modified it a little, now the backup files are zipped using 7zip instead of zip and at maximum compression ratio (7zip can compress text really, really well, so why not). I put it in the folder C:\DatabaseBackup as per the default for the script.

Next, I set up a scheduled task in Windows, to run the script every day. The action is "Start a program", the program/script is "sqlcmd" and the arguments are:
-i C:\DatabaseBackup\backup.sql -o C:\DatabaseBackup\output.txt -S .\SQLEXPRESS
Where .\SQLEXPRESS is the name of my (you guessed it) SQL Express server. You might need to do add some login credentials to these arguments, have a look at the sqlcmd documentation for the details.

Finally, before running the script for the first time, I had to enable the xp_cmdshell option in SQL Express. Make sure to read up on the security implications when you do so.

Now, this will not give you any notifications when the SQL script is unable to backup the databases. On another server, I installed Vale Express Agent to get notifications when the SQL fails. To do this, make sure to paste the SQL directly into a new backup job (don't use sqlcmd to call the script!).

Where and how to backup?

I've been working with Amazon S3 lately and S3 was also mentioned in the podcast that I mentioned earlier. Basically, Amazon makes sure that your data is in at least two locations in the world at all times. Also, S3 is terribly inexpensive, so it seemed like a good idea to backup to their servers.

Enter JungleDisk. I'd heard about JungleDisk before, it can backup all of my data to S3 and it is dirt cheap. It's only $5 a month for a server edition (which runs the backup as a Windows service), this includes the first 10 GB of storage for free! Great deal, as I currently only have a few hunder megabytes to backup anyway.

JungleDisk also natively supports backing up NTFS file permissions, which is exactly what I need.

Setting up was quite easy, however I was suddenly stuck in a "looking for server" screen after entering my JungleDisk credentials. As it turns out, the first time you set up the software, you have to start "Set License Key for Jungle Disk Server Edition" first. After that, it was easy to add the folders I needed and exclude .mdf/.ldf files.

How to restore?

Apparently, this is the most important part of my backup strategy… And I'm being dumb about it, because I haven't tried restoring at all. I mean, yes, I've restored a JungleDisk backup to see if I can get my files back, but that's it.

I am prepared to spend a few hours rebuilding my server if something happens to it. Currently I don't have much data and a simple deployment strategy, so this should not be a big problem.

I'll revisit the restore part once I have to move to a much bigger server, but by then, I'll probably also have to revisit the backup strategy. As I said, it's basic.

10 PRINT "REALLY BASIC"

20 GOTO 10

RUN

In the past few weeks, I've been tweaking the site for performance and noticed that there were an aweful lot of SQL queries being performed in the database. As it turns out, calls to the umbraco.library:GetMedia() method are being sent directly to the database. This meant that for each media item, three queries are being performed. Times a 120... That starts to hurt a little.

Also, it is impossible for us to turn on caching on this macro completely because updating the media item with a new image would not expire the cache.

I had to come up with something else that would cache calls to the media library. So today, I'm presenting you the Cultiv MediaCache package.
This package provides an XSLT extension that provides a caching mechanism for calls to the "GetMedia" method.

It's very easy to use:
In your XSLT files, instead of doing calls to umbraco.library:GetMedia(), you do them to Cultiv.MediaCache:GetMedia().
That's it! Told you it was easy.

Read all about it on the project page, download it, use it, vote it up. Okay, thanks! :-)

Tiny update dec 20, 2009 - 17:28: Now compatible with .net 2.0 installs of Umbraco (previously only worked on .net 3.5).

Sign up for Unfuddle and log in to your account (through your_account_name.unfuddle.com). Go to "Repositories" and create a new Git repository.

Now you have to create an authorization key, to be able to log in to the Git repository remotely.

Go back to Visual Studio and click Git's "Browse repository" (the folder icon) button again. Then in the menu go to "Remotes" > "PuTTY" > "Generate or import key".

Make sure the settings for generating the key are correct, the key needs to be 2048 bits.

After you've generated the key, change the key comment to your e-mail address, and enter a passphrase for the key. Now, make sure you copy the key from this window! Saving the public key generates a slightly different format, but Unfuddle really needs the format as it is in this window.

Save the public and private key somewhere anyway, you'll especially be needing the private key later.

In Unfuddle go to "People" > and edit the Account admin. In the bottom left you can enter a "New public key...".

When that key is accepted, go back to the "Repositories" tab and find the repository server, under your repository title (something like git@your_account.unfuddle.com:your_account/abr.git), copy this address.

Now you can set up the remote server in Visual Studio. In the menu bar, click "Git" > "Manage remotes". Give your remote server a name (no spaces) and paste the address you just copied.

Browse the private key that you stored earlier and choose hit "Load SSH key". Enter the password for that key and then you can save the connection. For some reason the "test connection" button fails for me ("ERROR:gitosis.serve.main:Need SSH_ORIGINAL_COMMAND in environment."), it still works though.

So now you're ready to push whatever is committed in your current branch to the remote server, use the blue up arrow ("Push changes to remote repository") to do so. You could also then push all branches and tags, or do a pull first to resolve any merge conflicts if you want.

In the next part of this series, I'll give a quick rundown of branching and merging.

First of all, go and download and install the Git extensions for Windows. The featured (full) release is recommended.

In Visual Studio, you'll now see a few new buttons (in Windows Explorer, there's also some new context items that will show up when you right-click a folder).

As you can see it's a tiny toolbar, click the last icon (settings), you have to set a name and e-mail address, they will be attached to any commit you do.

I've noticed that in order for the toolbar buttons to work, I have to open a file in the solution. So just open one of the files and make sure the cursor is in the file somewhere.

Hit "Ok" and click on the folder icon ("Browse repository"). You'll be presented with a screen with three options, one of which is "Initialize repository".

Initialize the repository in the root directory of your solution, this is typically where your .sln file is. The content in this folder and everything in the subfolders will be under source control. This is also your personal repository, there is not even a central repository yet.

The repository is simply one .git folder in the solution folder.

Almost done!

You're ready to commit your project to the repository. First, make sure you ignore the appropriate files, hit the "edit .gitignore" button and add the default ignores. For me personally, this is all that I need, you might want to tweak it.

Ready. Now you can do your first commit! You can skip the "Add files" button, this will just stage all the files for a commit, you can also do this in the commit screen.

Select all of the files and click "Stage selected files", type a commit message and click "Commit".

This creates the first branche, called master. You're good to go code and make changes. When you're ready to commit again, just use the tiny toolbar button instead of the repository browser.

In the next part of this series, I'll show how to commit the changes to a remote repository using Unfuddle.com.

Enter Git, my saviour. For now. I have literally worked with Git for three days, so I know very little and I can't claim that it will be any better than the rest of them, but it sure seems like a great system and I've seen very good reviews online.

Advantages

Working with Git, as opposed to other source control systems has some key advantages.

Git is great for experimental projects, where you want to give your developers the power to experiment wildly without any of their experiments getting into the source control system if they don't work out. Making a new branch in Git is easy, merging the branch back is quick and simple. Git just gets out of your way and does the hard work for you.
Of course you could still have merge conflicts sometimes, and they need to be resolved by hand, but at least you can trust the rest of the merge to go well (unlike the horrors I've seen in CVS and SVN).

One of the things that I really like is that Git only creates one folder in your source code file structure and not one folder for each directory (like CVS/SVN). Git also does not require all your files to be read-only, like in TFS. And finally, you can just move/delete files without all kinds of errors popping up, Git just detects the move or deletion.

I have a local repository of all of the files and history my project, I can commit frequently to the local repository and when I am satisfied about my work, I could send it to a remote, central repository. Having a distributed repository also means that I am never tied to a network/internet connection to use source control.
Also, when the central repository is down, I could just find a team member that has a recent copy and pull down their repository while I wait for the central server to be fixed.

Using the Git Extensions for Windows gave me another nice little productivity nugget: a sensible and (as far as I can tell) complete list of files that need to be ignored while committing changes. Everything from "Thumbs.db" to the Resharper folders is in there, cool.

As I understand it, Git also works great with large sets of files and large teams. The Linux kernel is under Git source control and that's a lot of files and a lot of collaboration.

There are plenty more features that are cool like cherry-picking commits, the built in CVS proxy server, octopus merging, etcetera. If you want to read more, go and have a look at the Git Wikipedia article. There are some great video's on YouTube as well if you want to understand Git better. Remember that on the Windows side, you don't even need to know the command line syntax.

Disadvantages

I really haven't found any disadvantages yet to using Git. Sure, it's a new system and there's a few things to learn, but that's about it. I've only spent about a day understanding Git and I feel very comfortable already.

Of course, once I start using it more often and in a team scenario, I might run into some difficulties, we'll see.

In the next post, I'll show how easy Git is to set-up and use in Windows with Visual Studio (again, unlike for example SVN).

In normal day-to-day use this is not a problem, but it becomes one when you try to programatically access the documentType by alias (DocumentType.GetByAlias("Folder")). I ran into this problem the other day and couldn't figure out why I was getting unexpected results until I had a look at what the ID actually represented, a media folder.

This could be considered as an "Umbraco tip of the week", however this applies to ASP.NET webforms in general as well.

I thought about applying styles and maybe some Javascript hacking to make the login form look exactly like the design. Then, after some searching on the internet, I found out that it is actually extremely easy to apply any layout to your login form.

I started out with this:

<form runat="server">

<asp:Login id="Login1" runat="server" />

</form>

The designer had made some prettier input boxes with background images and the "Login" button was actually style link.

You can actually use something called a LayoutTemplate from
within your login control.

The easiest way to do this is to:

• Open up your master page in Visual Studio
• Go to the designer view Right-click the Login control and choose "Convert to template"
• Start customizing the HTML

However, if you want to do this manually (and who doesn't love some manual tinkering), you have to keep in mind that you need to put at least three controls in your login control:

• An asp:TextBox control* with an ID of: UserName
• An asp:TextBox control* with an ID of: Password
• Either an asp:Button an asp:ImageButton or an asp:LinkButton control with a property: CommandName="Login"

* When I say a TextBox control, I actually mean a web control that implements ITextControl.

If you want to show an error when the login fails, add an asp:Literal with an ID of: FailureText

In the end, you'll end up with a piece of code that looks a bit like this (custom styling removed to keep this nice and short):

<form runat="server">

<asp:Login id="Login1" runat="server">

<LayoutTemplate>

<asp:TextBox ID="UserName" runat="server"></asp:TextBox>

<asp:TextBox ID="Password" runat="server" TextMode="Password"></asp:TextBox>

<asp:LinkButton ID="submitLoginBtn" CommandName="Login" runat="server">Login</asp:LinkButton>

<asp:Literal ID="FailureText" runat="server" EnableViewState="False"></asp:Literal>

</LayoutTemplate>

</asp:Login>

</form>

Update: As Dirk and Jan point out, this method will still produce a table surrounding the login controls. This is only a wrapper though, no table element go between the input tags, not to worry.

Dirk is actually working on getting the ASP.NET 2.0 CSS Friendly Control Adapters to work with Umbraco. Mind you, these adapters are available for .NET 2.0 only.

I personally set-up all my Umbraco installations with the .NET 3.5 config, so this method would not work for me. I don't view this as a big problem, I just style the wrapping table and ignore it.

First of all, I thought I'd enable Windows authentication om my /umbraco folder. Couldn't be easier, right? Wrong.
Apparently, since I am using the .net 3.5 configuration to run Umbraco in integrated pipeline mode in IIS7, some weird problem was introduced:

I could not disable forms authentication on the /umbraco folder. Googling for this, did not get me a lot of good results. However, I finally figured it out and it was actually a quite easy fix, the following section in the web.config needs to be disabled:

 <authentication mode="Forms">
<forms name="yourAuthCookie" loginUrl="login.aspx"
protection="All" path="/" />
</authentication>

After disabling the forms authentication section, I could easily enable Windows authentication on my Umbraco folder and disable anonymous access. Great!

This seems to be an unintentional "bug" that I've submitted (you can vote, if you care) to the core team for future consideration.

After that, I thought I'd also make it impossible to show the debug information on my live site. I had actually linked to an Umbraco book about this in an earlier post, so that should be easy, right? Wrong.

I immediately saw a glaring mistake in the rewrite code, it relied on me having ".aspx" in all of my URL's. But since I have set "useDirectoryUrls" to true (so that none of my pages end in ".aspx"), this would not work.

Maybe this book was written before you could even enable useDirectoryUrls, I'm not sure. I've made a new wiki article for it though.

The solution is as follows, any URL with a querystring in it, starting with umbDebug should be rewritten:

<!-- Prevent the umbDebug querystrings from being used -->
<add name="nodebug"
virtualUrl="(.*)umbDebug.*"
rewriteUrlParameter="IncludeQueryStringForRewrite"
redirect="Application"
destinationUrl="~$1"
ignoreCase="true" />

Updated: Or... as Dirk and Shannon point out, in Umbraco 4 you can just disable the debugging by using:

<add key="umbracoDebugMode" value="false" />

The resulting XML is 100% compatible with the sitemap.org specifications (which should be supported by all the major search engines).

Of course this generator will take into account the umbNaviHide property. Also, if there is no template attached to a content item, then the resulting output would be a blank page. So these pages are not included in the sitemap either.
I ran into this problem because Tim's excellent blog package that I'm using generates some date folders that should not be in the sitemap.

I would've liked to do everything in the XSLT, but the <urlset> node absolutely had to be on the second line of the resulting XML before Google would accept it. So I had to put that part in the template.

Have fun with it and don't forget to use the thumbs up if you like it, thanks!

Here's a few screenshots to show that it is highly configurable:

Of course you can just enter some content and add the bodyText field to your template to make it show up on the contact page. Here you can see I added a "Thank you" page. After the website visitor submits the form, they will be redirected here. You can configure any other page that you want.

Here again a reference to the thank you page. The form is completely empty by default so it might be a good idea to fill in the label names here.

The error messages are also empty by default, add whatever text you need here.

And finally you can set up some properties for the mail that will be sent.

The default XSLT navigation templates only work when you add a node under "Content" and then all of your content under that. Luckily, it's easy enough to move all your content under a new item. But what should that item be?

I tend to start with a document type of "RedirectFolder", for example this is what my content section looks like right now:

The documentType contains two properties of the type "contentPicker" and their aliases are umbracoRedirect and umbracoInternalRedirectId. Once you pick a page, the redirecting will be done automagically by Umbraco.

The umbracoInternalRedirectId property kind of does what it says: it will load the selected page's content transparently; no url change. Thanks to Doug Robar for telling us about this hidden gem at CodeGarden '09!

Using the URL rewriting feature, you can also disable the debug querystrings so that you don't disclose too much information on your live server, see the Umbraco book on how to do this.

I was developing a custom module earlier this week and noticed that I could just add a trace.write statement to see why it did not work on the live server. Turns out that the problem was somewhere else completely, which I quickly found out once I started adding some trace statements. Nice!

CleanHome will give you a ContentPage document type linked to a master page that sets you up with an XHTML 1.0 strict document type.

The document type includes these new fields:

• body (richtext editor)
• meta keywords
• meta description
• alternate title (to use in <title> tag for example)
• alternate navigation title
• hide in navigation checkbox (alias: umbracoNaviHide, to use with default XSLT templates)

There's also a stylesheet reference and a favicon reference in the master page.

The stylesheet contains Eric Meyer's reset-styles to start you off with the cleanest possible page.

Your new "home page" validates as XHTML strict and the CSS file is also completely valid.

Warning: This will create a document type and Master/Childpage with the name "ContentPage", a content item named "Home" and a CSS files called styles.css. If any of these already exist in your site, you WILL get errors.

This package is specifically meant for new, empty websites. You can view it as a bare-bones version of the Runway package.

Download CleanHome here.

"all of your style sheet and JavaScript files in your ASP.NET web application can be automatically minified, compressed, combined, and cached".

http://www.codeproject.com/KB/aspnet/CssAndJavaScriptOptimizer.aspx

The simplest way for me has been as follows.

When I create a new Umbraco website, I make a structure in my development folder of three folders under the site's name:

Database
UmbracoFramework
UmbracoModules

Logically, my database mdf/ldf files go into the "Database" folder. I do this to have everything belonging to the site close together.

In UmbracoFramework, I place the cleanly downloaded files of Umbraco's install. I've changed the default web.config to the .Net 3.5 version, using directory URL's.

One important thing to note is that, for this to work in Windows 7 (and probably Vista), you need to run Visual Studio as Administrator. If you don't, the debug session won't start. If there's any work-arounds for this, I'd love to know.

So let's see what we'd need to do in Visual Studio.

After starting VS2008, we create a new (blank) solution for this project.

Then we add an existing website (note you can do this either before installing Umbraco locally or right after right, it doesn't matter).

In your build configuration manager, make sure never to build this project, there's no need.

Now we can start creating a user control, add a new ASP.NET Web Application project in the folder UmbracoModules. We'll call this one (surprise!) "HelloWorld".

So a HelloWorld folder will be created under UmbracoModules.

We won't need the web.config and default.aspx, so I delete them.

We can automatically copy the dll/pdb files and the ascx files to the UmbracoFramework folder during each build. This is done using the post-build events:

XCOPY "$(ProjectDir)bin\HelloWorld.*" "$(ProjectDir)..\..\UmbracoFramework\bin\" /y
XCOPY "$(ProjectDir)*.ascx" "$(ProjectDir)..\..\UmbracoFramework\usercontrols\" /y

Note that "Helloworld.*" is the name of the dll/pdb's we want to copy. Don't use *.* here if you reference the Umbraco framework files, else they'll get copied over the existing verions each time.

For both the UmbracoFramework AND the new module, we'll change the default webserver into a "custom" one. This is just a link to the local domain name we created in IIS.

Once everything is saved, we're done. We can start creating a new user control and put breakpoints in them.

Hit F5 and see what happens.

Voila! A breakpoint being hit, we can start debugging.