Getting started with Orchard Core as a NuGet package

UPDATED: This post was updated in May 2018 to reflect changes in the process since the original post was created.

Orchard Core is the next big thing in Orchard. It's exciting to see the project get close to release, and every demo I see of the project, I get more and more impatient for the official release.

In this article, we're going to look at just how easy it is to get Orchard Core running in an existing web project by installing the Orchard Core NuGet packages into our solution. This approach allows you to pick and choose which aspects of functionality you want to use, and which you choose to leave out.

Let's get started

In order to install Orchard Core into an existing web project, you'll first need an existing web project. Orchard Core runs on .Net Core 2.0, so you'll need to make sure you have it installed before you continue.

First, fire up Visual Studio, and create a new ASP.NET Core Web Application:

New Project Dialog

Make sure you create an empty .NET Core project that targets ASP.NET Core 2.0. 

Project Type DialogBuild and run your project, and you should see the default 'Hello, world!' message in your browser. Now we have an existing web project that we can install Orchard in to, so let's get started...

Installing Orchard Core

This is as simple as installing a NuGet package into your web project. I mentioned earlier that you are free to pick and choose which aspects of Orchard Core you add to your project, and this is where you'd do it. However, we're going to keep it simple, and we're going to go ahead and install the package called OrchardCore.Application.CMS.Targets.

What is OrchardCore.Application.CMS.Targets? Well, it's basically a collection of other packages. It contains everything you need to get a fully fledged CMS up and running. Take a look at the dependencies for this package, and you'll see all the components of Orchard Core that it includes. Most of them are modules, but it also includes a handful of themes to get you up and running.

NOTE: At the time of writing, Orchard Core is in beta, which means that you'll need to check include prerelease in order to see the Orchard Core packages show up in the package manager.

ANOTHER NOTE: The nuget.org feed only contains the verified releases of each package. If you'd like the bleeding edge packages (built from the master branch after each commit), you can get these versions from MyGet; all we need to do is add the MyGet source to our list of package feeds: Back in Visual Studio, click Tools > NuGet Package Manager > Package Manager Settings, then in the menu on the left, make sure the 'Package Sources' option is selected. You're going to want to add a new package source, the Source is 'https://www.myget.org/F/orchardcore-preview/api/v3/index.json', and I gave mine the name of 'Orchard Core Preview'.

Once you've installed that package, you're almost there. Next step:

Telling our web app to use Orchard Core

If you build and run the project now, you'll still see the default 'Hello, world!' message. But we've installed Orchard Core, so what gives?

Well, we need to tell our app to use Orchard Core. Thankfully, this is really easy to do.

Open your Startup.cs file. You'll recognize this file if you've ever worked with an ASP.NET Core web project before; but if not, this file is basically your app's entry point. This is where we'll configure our web app to use Orchard Core:

Add the line

services.AddOrchardCms();

into the ConfigureServices method.

Next, in the Configure method, replace the lines

app.Run(async (context) =>
{
await context.Response.WriteAsync("Hello World!");
});

with

app.UseModules();

My whole startup class now looks like this:

 public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddOrchardCms();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseModules();
}
}

That's it. You can now build and run, and you'll see the Orchard Core setup page. Once you've completed the setup, your site will be ready to go!

Blog Screenshot

Next Steps

Want to extend the default functionality? How to create a custom module or theme for Orchard Core.

Password requirements too strict for local development? How to change the password requirements for Orchard Core sites.

Wait, where are my logs? Orchard Core as a NuGet package - getting logging working.

Fancy a bit of Service Fabric? Orchard Core and Service Fabric - Introduction.

9 comments

  • ... Posted by Antoine Griffard Posted 09/22/2017 01:04 PM

    Great sample Chris. I can't believe how fast it is to create an application, add the nuget packages, configure the startup, add a recipe and launch the setup.

    By the way, your fix has been merged and the setup now displays a message when no recipes are found.

  • ... Posted by Sipke Schoorstra Posted 09/22/2017 06:12 PM

    Looks like Sébastien fixed the issue with the recipes!

  • ... Posted by kavya Posted 10/04/2017 09:34 AM

    great post chris

  • ... Posted by Hassan Posted 10/06/2017 05:36 PM

    hey chris, can you explain OrchardCore.AsModule package? Sebastien made a demo no ON.NET channel about that. thanks in advance.

  • ... Posted by Chris Payne Posted 10/10/2017 10:34 AM (Author)

    Hi Hassan

    I plan to do that as my next post, as soon as I get the time in the the coming week or so.

    I'll let you know once it's published.

  • ... Posted by Adam Posted 02/06/2018 12:29 AM

    Do you plan on showing how the MVC one works and getting started with it?

  • ... Posted by Ricky Ogtip Posted 03/27/2018 07:15 AM

    Hi Chris,

    I've tried to use your example to create a CMS app, however I find out that my Custom Module are no longer available in the Admin Modules List. If I use the OrchardCore.Cms package these Modules appear in the Uncategorized List.

    May I ask what I am missing so I can use my custom modules?

    Thanks,

  • ... Posted by AKAS Posted 04/28/2018 07:20 AM

    Hi chris, are you able to justify OrchardCore.AsModule package? Sebastien created a demo no ON.NET channel that. thanks earlier.

  • ... Posted by Chris Payne Posted 05/18/2018 12:12 PM (Author)

    My latest blog post explains the OrchardCore.AsModule package (now called OrchardCore.Module.Targets): Creating a custom module or theme for Orchard Core

Leave a comment