LibrarySites.Banner

Consuming Sitecore.Demo.Shared NuGet Packages

This article is the last part of a two articles series:
  1. Sitecore.Demo.Shared NuGet Packages Explained
  2. Consuming Sitecore.Demo.Shared NuGet Packages
If you have not read the first part, you are encouraged to do so before reading this one.

Packages Name Consideration

Sitecore.Demo.Shared modules assembly name format is Sitecore.Demo.[Layer].[Module]. This means that to consume the packages, you must not have assemblies with conflicting names in your own solution. E.g.: Sitecore.Demo.Feature.Demo.

Folder For Unicorn Items

Unicorn items from Sitecore.Demo.Shared NuGet packages are copied to the \items\Shared\[Layer]\[Module] folder of the consuming solution.

For example, installing the Sitecore.Demo.Feature.Demo (demo sidebar) NuGet package creates the following files:

items\
  Shared\
    Feature\
      Demo\
        Layouts\
        Renderings\
        Templates\
        .gitignore
 
Thus, you should have a \items folder at the same level than your Visual Studio solution file.

If you are not using Git for source control, you must replicate the .gitignore file intentions to your source control technology.

Sitecore Variable For Unicorn Items Root

As the Sitecore.Demo.Shared NuGet packages Unicorn configuration files use the $(sourceFolder) Sitecore variable in their target data store physical root path, you must define it in a patch file like this:
 
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <sc.variable name="sourceFolder" value="PATH_TO_YOUR_SOLUTION_ROOT_FOLDER\items" />
  </sitecore>
</configuration>

Where PATH_TO_YOUR_SOLUTION_ROOT_FOLDER is the path to the folder containing the consuming Visual Studio solution file.

If you are already using the $(sourceFolder) Sitecore variable for your own serialized items, it means that you must either:
  • Change the location of your Unicorn serialized items to \items\[Layer]\[Module].
  • Or use a variable other than $(sourceFolder) for your own Unicorn configuration files.

AppSetting For Activating Unicorn Configurations

As the Sitecore.Demo.Shared NuGet packages Unicorn configuration is only active if the unicorn:define appSetting is set to On, you must define it in your Sitecore web root web.config file like this:
 
<configuration>
  <appSettings>
    <add key="unicorn:define" value="On" />
  </appSettings>
</configuration>

The way you define it is up to you. An XDT configuration transform file is recommended.

Preparing the Consuming Solution

The content of NuGet packages from the Sitecore.Demo.Shared repository is often the base or parent of other work. For example, templates in a NuGet package are used as a parent for other templates in the consuming solution. For that reason, they must be deployed first by build scripts and MsBuild. The Sitecore demo team likes to use an additional "Build" Helix layer for that. Here is how the Sitecore.HabitatHome.Platform demo is organized:
 
src\
  Build\
    Build.Shared\
      code\
        Build.Shared.csproj
        Program.cs
  Feature\
  Foundation\
  Project\

This Build.Shared.csproj project file is a dotnet core console application project and its target framework has been modified to .NET Framework 4.7.1. It has all the package references for the shared NuGet packages:
 
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net471</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Sitecore.Demo.Feature.Demo" Version="9.2.0.63" />
    ...
  </ItemGroup>
</Project>

The Program.cs file is the default file that is created when you create the project:
 
namespace Build.Shared {
    public class Program {
        public static void Main(string[] args) {
        }
    }
}

The output assembly of this project is not required. The project is for:
  1. Copying the NuGet packages YML files to \items at build time.
  2. Deploying the NuGet packages views, configuration files, and other content files to the Sitecore web root.
This project must be built and deployed first when building and deploying the solution. To achieve this, the Build.Shared project can be checked as a dependency for all the foundation/feature/project layers Visual Studio projects in the "Dependencies" tab of the "Project Dependencies" dialog in Visual Studio (Project menu > Project Dependencies...).

Setting Up the NuGet Feed

To reference the NuGet packages, the feed must be added to the consuming solution nuget.config file in the following location:
 
<configuration>
  <packageSources>
    <add key="sc-demo-packages" value="https://sitecore.myget.org/F/sc-demo-packages/api/v3/index.json" />
  </packageSources>
</configuration>

Once this is done, the NuGet packages can be installed from the Visual Studio NuGet Package Manager window.

Installing a NuGet Package

After this is all setup, installing a NuGet package is a few steps:
  1. In Visual Studio, in the Solution Explorer, right-click on the Build.Shared project.
  2. Select "Manage NuGet Packages...".
  3. In the NuGet Package Manager, select the "Browse" tab.
  4. To see only the shared NuGet packages, either:
    1. In the "Package source:" dropdown in the top-right corner, select "sc-demo-packages".
    2. In the search box, type Sitecore.Demo. and hit the Return key.
  5. In the list, select the desired package.
  6. On the right side, click the "Install" button.
  7. Follow the instructions.

Front-End Assets

As the Sitecore.Demo.Shared modules are used in SXA and non-SXA websites, front-end assets cannot be in the shared module. They must be duplicated on the respective websites.

Most of the modules are consumed and used by these Sitecore demo sites:
Front-end assets can be obtained from these. For example, Sitecore.Demo.Feature.Demo demo sidebar assets are:

Updating NuGet Packages

The Sitecore demo team releases new versions of the shared NuGet packages regularly. To update your installed NuGet packages:
  1. In Visual Studio, in the Solution Explorer, right-click on your solution.
  2. Select "Manage NuGet Packages for Solution...".
  3. In the NuGet Package Manager, select the "Updates" tab.
  4. To see only the shared NuGet packages, either:
    1. In the "Package source:" dropdown in the top-right corner, select "sc-demo-packages".
    2. In the search box, type Sitecore.Demo. and hit the Return key.
  5. In the list, check all the packages to update.
  6. Just above the list, click the "Update" button.
  7. Follow the instructions.

Conclusion

I hope this article helped you understand how the Sitecore demo team is working with NuGet packages from a separate repository, allowed you to consume one or more of the packages, and even inspired you to setup a similar solution for your own projects.

For any question, you can reach the Sitecore demo team on the #habitathome channel of the Sitecore Slack community.