Visual Studio and Umbraco as a Service
In working with Umbraco as a Service (UaaS), we often get askeded the question is how to work with it using Visual Studio (VS). The answer up until now has been a rather manual process. I always get a little annoyed when advising people to do something manually when I know it can be automated. Automation is difficult to get right though, so I've been hacking away at a little script for the longest time but was never happy with it, it always seemed to be a little "half way there but not really". However, a few weeks ago I had a breakthrough that gets close to what I personally like to experience to start working with VS. TL;DR; - if you don't care about the background story, just scroll down to the end of this post to see a short video and a download link for the setup script.
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:
- 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.
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!
Alright, so where are we now:
- Create a new project on Umbraco as a Service
- 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:
- git clone `your custom code repository`
- 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:
- 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!