Apr 18, 2015

Growing your Orchard faster with some Nitrate

I initially wrote Nitrate about two years ago in PowerShell. The idea was to come up with a consistent Orchard development environment and build the tools to easily reproduce it across a team.

The scripts worked and served me well, but proved hard to reuse by others due to dependencies. Plus PowerShell is not all that fun to work with and maintain. So I spent some evenings rewriting all of it as a plugins based C# command line application instead.

The new Nitrate is much more flexible and general purpose. But here I will focus on how it can fulfill its original purpose: making it easier to work with Orchard.

If you'd like to dive right in, you can find Nitrate on GitHub or in the Chocolatey repository.

What can Nitrate do for me?

  • Commit only your code to source control.
  • Do not touch Orchard code, so you can easily upgrade to a new version, or your own fork.
  • Easily build and keep a consistent environment across a team.
  • Automatically configure SQL Server.
  • Easy database backup and restore (great for migrations!)
  • Only adds one small configuration file to your repository.

Requirements

You'll need the following to fully enjoy Nitrate:

  • Visual Studio Command Prompt (so you can use MSBuild)
  • Git
  • SQL Server
  • IIS Express (should come with Visual Studio)
  • Chocolatey (to install Nitrate)

You may want to take a look at my post about my favorite command line setup for a wait to configure some of these tools and make your command line experience overall more enjoyable.

Quick Start

Nitrate is very flexible, but I built in a sample configuration that will setup Orchard easily. You'll first need to install it:

choco install nitrate -y

Then, go to an empty directory and initialize it:

no3 init

This will create the sample configuration file, nitrate.json. Feel free to take a look at it. When you're ready, run:

no3 run:setup

This will take a few minutes to download, build and setup Orchard. If all goes well, your web browser will automatically open to your local Orchard instance when everything is done.

Nitrate Commands

Commands are implemented by plugins, one command per plugin. Each plugin can have more than one set of configuration options in the nitrate.json file, each set indentified by an arbitrary name.

The nitrate command line format is the following:

no3 <command>[:<configuration>] [<subcommand>] <options>

Where:

  • command is the required command name
  • configuration is the name of one of the configurations found in nitrate.json. If no name is provided, the plugin will be run on all configurations found in sequence.
  • subcommand is a plugin specific sub command, not all plugins support them.
  • options is the optional set of parameters that the plugin or its subcommand can use.

To view a list of available commands, run:

no3 help

You can specify a command name for more details, for example:

no3 help run

There's currently no documentation for plugin configuration options in nitrate.json but the default file should be relatively self explanatory. And until I get around to writing documentation, you can also explore the source code on GitHub.

Project Organization

You can configure Nitrate to work pretty much any way you want. Here I will describe the project organization that has worked for me so far.

Folder structure

One of my main objectives was to be able to commit only my own code to source control and not touch Orchard directly. This way I could update it at any time, be it to a new version or maybe even my own fork.

So I've decided on a simple folder structure:

  • orchard: contains a clone of the Orchard git repository
  • db: contains my database backups
  • src: my own source files
    • modules: my custom modules
    • themes: my custom themes

As I use Git, I also added the following to the .gitignore file:

orchard\
db\

This way they will not get committed.

If you're familiar with Orchard, you'll be wondering how I can run my modules if they're not in the orchard\src\Orchard.Web\Modules folder. It turns out that symbolic links, albeit rarely used on Windows, are pretty well supported. And so one of the plugins I wrote for Nitrate takes care of adding a link in Orchard's Modules folder to each folder in src\modules. I also do the same for themes.

Visual Studio

For Visual Studio, I create a solution file and organize my themes and projects using solutions folders. I also create an Orchard solution folder and use Visual Studio's Add > Existing Project... context menu to add Orchard's entire solution file.

There is one caveat: I have to manually edit the solution file to alter the path of my custom modules and use the symlinked path. For example:

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Nwazet.Commerce", "src\modules\Nwazet.Commerce\Nwazet.Commerce.csproj", "{909ACC2C-D672-4752-B75B-6822E05FE0E3}"

needs to be changed to:

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Nwazet.Commerce", "orchard\src\Orchard.Web\Modules\Nwazet.Commerce\Nwazet.Commerce.csproj", "{909ACC2C-D672-4752-B75B-6822E05FE0E3}"

This will ensure that Visual Studio uses the right paths when referencing other projects.

Creating modules and themes

I like to use Orchard's code generation module to create new projects. The only thing is it will create the module in Orchard's normal module or theme folder. Currently, I need to manually move the entire folder over into src\modules, but Nitrate can already help build the symbolic links:

no3 symlinks:modules create

In the future, I plan on making the whole process easier with a single Nitrate command.

Using third party modules and themes

Once Orchard is setup, you can install modules from the gallery to it. However this is not something that can be automated yet. You could get close by using an Orchard recipe though.

If you're using third party modules or themes hosted in a Git repository, you can also add them to the Git settings in nitrate.json, and clone them to a folder of your choice. For example, you could place them straight in Orchard's Modules folder or configure the SymLinks settings to automatically create the symbolic links for you.

Working with the database

How many times have you worked over and over on a module's migration before you could get it right? That's happened to me more often than I can remember. And this is probably the most useful feature of Nitrate right now, it can quickly and easily back up and restore a local SQL Server database.

To back up the current state of your database, just run:

no3 sqlserver backup

And if your migration is not producing the expected result, all you need to do is:

no3 sqlserver restore

That's it!

IIS Express

If you've run the default setup, you already noticed that Nitrate can handle IIS Express. Note however that right now this does not support HTTPS. If you need to work with SSL in Orchard, you should configure and run IIS Express from within Visual Studio instead.

Troubleshooting

I noticed that the latest versions of ConEmu will interfere with how Nitrate runs external programs like Git and MSBuild by opening them in another tab. You can fix that behavior by changing the ConEmu settings, under Features, uncheck the Process 'start' option and all should be well.

Going Further

There's plenty that Nitrate can do for you, and even more that it can't yet do. Take a look at the GitHub page, look through the code. Fork it and write your own module. If you think it can help others, send me a pull request and it could get included in the next version.

Of course that can become time consuming, so if you have a suggestion or if something doesn't work well, make sure you file an issue.

Comments powered by Disqus