Friday, January 17, 2014

Heads-up, breaking change coming in 7.0.2 and 6.2

We're hard at work on v7.1 (and 6.2) of Umbraco which will include major improvements to Members: In order to make these improvements, we need to introduce a change that *can have* breaking side effects for some packages.

As a matter of constant care, we've decided to introduce this change in 7.0.2 to make sure that the increasing number of package developers for v7 gets access to the change as quickly as possible.

Normally we do not allow a breaking change in patch or minor versions, but as the change will only affect a minority yet the side effects will only increase over time, we decided that it was best for all if we did it as quickly as possible and informed about it so package developers can make the changes necessarily, thus making sure that sites won't be affected when upgraded.

The underlying problem

With the new UmbracoApiController there is no way for us to tell if the controller is being used for the front-end or the back-office. Without knowing if the request is for the front-end or back-office, this causes problems with how we authenticate Users and Members and also causes problems with how we assign the Culture to the current request for a given User or Member.

The fix

We need to change how a back office UmbracoApiController is routed so we can determine based on a URL path if it is a back office request. To do this we’ve created a new attribute: [IsBackOffice]. By attributing any UmbracoApiController with this attribute, the routing will change for that controller to be:


or if the controller is a plugin based controller, then the route will change to be:


The good news is that this attribute is inherited, so we’ve decorated the UmbracoAuthorizedApiController with the [IsBackOffice] attribute which means that you will most likely not have to change any of your controller code because if you are using an UmbracoApiController in the back-office, 99% of the time you will be inheriting from UmbracoAuthorizedApiController.

Who is affected

There are 2 scenarios where you may be affected by this change:

  1. You are using an UmbracoApiController for the back-office but are not inheriting from UmbracoAuthorizedApiController.
  2. You have hard coded your UmbracoApiController service URLs in your JavaScript code

How to update (based on the above 2 points)

  1. You will need to add the [IsBackOffice] attribute to your UmbracoApiController implementation.
  2. If you’ve hard coded your service URLs, you will need to update them with the new “/backoffice” prefix mentioned above. However, It is good practice to never hard code any URLs based on both WebAPI or MVC controllers because routes can change. The UrlHelper for both WebAPI and MVC should be used instead to generate the URL for a particular route.
    • A good example of when routes may change globally is if you have a versioned approach to your REST implementation and perhaps on a new release you wanted to change all of your REST calls to use the new v2 version of your API calls, if you are using the UrlHelper to get your URLs, you don’t have to change any of your code.
    • So how do you get urls generated from the UrlHelper in c# into your JavaScript? In 7.0.2 there is a new event: ServerVariablesParser.Parsing which will allow you to insert any key/value pairs that you would like into the outgoing JavaScript object: Umbraco.Sys.ServerVariables which you can then reference. So by subsribing to this event you would be able to insert your service URLs into the ServerVariables in c# using a UrlHelper.
    • Use an MVC GlobalFilter

We’ll try to get some examples of these fixes up next week so you have an easy to follow guide on how to update Smile

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox