Publishing Service v2.0 - Quick Start Guide
This quick start guide is designed to get you up and running with the Publishing Service so that it can be evaluated in a local development environment. This guide does not go into specific detail about each action. More in-depth information can be found in the full Installation and Configuration Guide.
The goals of this guide are to:
- Setup the Publishing Service to connect to our Sitecore databases.
- Run the Publishing Service in Development mode.
- Install the Publishing Service package into a clean instance of Sitecore.
- Run a basic publish.
- Install the Publishing Service into IIS.
Prerequisites and Assumptions
It is assumed that a new/clean version of Sitecore 8.2 Update 2 (rev161221) is installed.
TIP : Sitecore can be installed quickly and easily using the Sitecore Instance Manager or SIM. More information can be found on the Sitecore Instance Manager site.
In this example, we have let SIM automatically install our SQL databases for us and they are named as such (Looking in SQL Management Studio):
Publishing Service Installation
If you havent done so already, go ahead and download the
Sitecore Publishing Service 2.0.0 rev. 170130 zip file from the Sitecore Developer site.
Installation involves simply extracting the zip file to the filesystem.
NOTE : For this guide we have extracted the Publishing Service to the path:
Configuring the service
Our first step is to tell the Publishing Service how to connect to our Sitecore databases so that it can read and write to them. To do this we will be using the command line. This can either be a PowerShell or normal Command Prompt window.
NOTE: The command window must be started as an Administrator in order to perform some of the actions later on.
Sitecore.Framework.Publishing.Host.exe : this is the main executable that will run the service but has a set of built-in tools that will help us to set up and configure everything we need.
Setting up connection string
The Publishing Service has a set of
commands that allow us to perform certain helpful actions as we run and configure the instance.
(More information on commands can be found in Chapter 4 of the Installation and Configuration Guide)
The first command we will run is
configuration - this allows us to modify a section of configuration.
It has a special sub-command called
setconnectionstring specially designed for supplying connection string information that will allow the Publishing Service to connect and work with Sitecore databases we have in our setup.
It is invoked as follows:
TIP : You can find extra information about any command or sub-command by adding
--help to the end of it.
For our example, we want to setup connection strings for the
If we take
core as our first example. To write the configuration setting we pass the parameters
core plus our connection string for the core database to the
.\Sitecore.Framework.Publishing.Host.exe configuration setconnectionstring core ‘Data Source=.\SQLEXPRESS;Initial Catalog=sc82rev161221Sitecore_core;Integrated Security=False;User ID=sa;Password=12345;MultipleActiveResultSets=True’
NOTE: The command will automatically add
MultipleActiveResltSets=True to the end of any connections strings - this is needed so that we can communicate to SQL Server in batches.
More information can be found in the Installation and Configuration Guide.
Doing this for each of the three databases should result in output like this:
These commands will have created a file called
sc.connectionstrings.json in the
global folder of the
config folder found in the root of the Publishing Service installation directory (in our example
Opening this file in a text editor can confirm that they have been added correctly.
TIP: Any configurations located in the
global folder are available to all environmental configuration types (for example
NOTE : You can read how the different configuration folders are used in the Installation and Configuration Guide.
Installation of the schema tables
For the Publishing Service to function correctly, we need to install a set of support tables into the SQL databases. We call this the schema.
This is where we use our second command
We need to issue the command:
.\Sitecore.Framework.Publishing.Host.exe schema list
This will check the schema versions installed to each database. This will also validate that we can connect to the Sitecore databases correctly.
You should get an output like this:
This shows the current schema version to be
Not Installed. This is expected as these are clean databases that have not had the Publishing Service installed onto them before.
NOTE: If you get any errors while running this command you may need to check your connection strings or account permissions.
We now need to
upgrade (install) the schema on each database. We do this with the
.\Sitecore.Framework.Publishing.Host.exe schema upgrade --force
You should get an output like this:
To validate the installation just run the
schema list command again.
We can now see that the databases are all running schema version 2, which is needed for v2.0 of the Publishing Service.
Starting the service in ‘Development’ mode
We are now ready run the Publishing Service for the first time.
By default, the Publishing Service outputs any messages to a log file (found in the
For this example, we are going to temporarily run the service in
Development Mode. This mode will allow us to see Debug (DBG) message output and also everything will be logged to the console as well as the log file.
This is useful for diagnosing any errors in these early setup phases.
To start the Publishing Service in
Development Mode you need to pass the parameter
development to the
.\Sitecore.Framework.Publishing.Host.exe --environment development
The Publishing Service will start up and you should see output like this:
The Publishing Service is now running in
This is running directly from the console, you can shut down the service by pressing
NOTE: If you start the service without the
environment switch then the service will start in
Production mode which only shows
Information (INF) level messages and outputs only to the log file.
There is a lot of information being displayed here, this is obviously too much for regular day-to-day usage but helps us diagnose any problems and see what modes and configuration switches have been enabled.
Keep the Publishing Service running for now while we install the Sitecore module package.
Installing the Publishing Service Module package
The second zip you need to download is
Sitecore Publishing Module 2.0.0 rev. 170130 which is available on the Sitecore Developer site.
Log into Sitecore as an
Administrator and locate the
.. and install / upload the
Sitecore Publishing Module 2.0.0 rev. 170130 package.
Once the installation has completed you should now see new configuration files in the
We need to edit one of these files.
Open the one called
Sitecore.Publishing.Service.config and change the
PublishingServiceUrlRoot value. This tells Sitecore which URL the Publishing Service is running on.
Until we install into IIS (later in this guide), the Publishing Service will be running on
http://localhost:5000. This is the default URL and port for the service to try and run on.
Running our first publish
Log into Sitecore as an administrator (as we will be needing elevated permissions for this next step.)
We now need to open the new
Publishing Dashboard. This is a SPEAK application that allows us to monitor what’s going on with the Publishing Service from inside our Sitecore CM instance.
We load the dashboard by selecting the newly installed
Publishing icon from the
We are going to be publishing all items in repair mode. You can think of this like
republish in the old publishing system (but much faster!).
As we are logged in as an administrator we can see the ‘Publish all items’ button at the top left of the dashboard.
Click this and select
We are instructing the Publishing Service to publish every item in our Sitecore instance.
When the publish runs normally it will compare the source item being published with the corresponding item on the target and skip that item if it sees that no fields have changed. (source is often ‘master’ and target is often ‘web’).
Repair mode tells the Publishing Service to skip this comparison and publish everything again.
We are using this example as this will display the most output and help you see what the publish is doing in the different stages.
NOTE: As this could be an expensive operation and not something that should occur often and not be needed by regular users, it is restricted to Administrator level accounts only.
Once you click the
Publish button the publish is queued and you can switch back to your command window.
You will see output similar to this:
There is a lot of information here but what you are seeing is that the publishing job was queued, then accepted and then processed.
The key thing to look for here is that
Complete – OK message at the end. This means that everything worked correctly.
You can also validate that the publish completed successfully by looking in the
Recent Jobs panel of the dashboard.
You can click on a row and see the details about that publish.
Hosting the Publishing Service in IIS
To host the Publishing Service in IIS you must have installed
Windows Server Hosting (.NET Core) which can be downloaded from Microsoft.
This allows the Publishing Service process to be correctly hosted in an IIS process and lets IIS manage the lifestyle of the process from IIS Manager.
Install into IIS
Having the Publishing Service run from a command window is great for debugging and development but not ideal for production or day-to-day usage.
Instead, we are going to use IIS to host the Publishing Service, this means that when IIS starts it will bring up the Publishing Service and manage all connections to it and restart it when necessary.
To install into IIS we need to use another command, this time called
NOTE: If you haven’t already done this, stop the Publishing Service using Ctrl+C in the command window.
We need to issue the command:
.\Sitecore.Framework.Publishing.Host.exe iis install --hosts --force
--hosts switch tells the command to update the hosts automatically file for you.
This should produce output like this:
This shows that the Publishing Service has been registered with IIS under the default instance name of
You can confirm this installation in IIS Manager itself.
We now need to update the
PublishingServiceUrlRoot setting we ammended earlier in the
App_Config/Include/Sitecore.Publishing.Service.config file and point it to the new IIS endpoint.
Once this is done you can restart IIS. This will start the Publishing Service instance.
Validating the IIS installation
The logs for the Publishing Service are stored in the
NOTE : In this example, they will be available in
If you open the log in a text editor, you should be able to see that the Publishing Service has started again but this time in the default
You can also validate the installation by going to one of the REST endpoints such as the
jobs status controller by opening
in your web browser.
Status:0 means that everything is working correctly and the service is running.
This quick start guide provides only a very quick example of how to set up the Publishing Service. More in-depth information can be found in the full Installation and Configuration Guide..