LibrarySites.Banner

Sitecore.Demo.Shared NuGet Packages Explained

This article is the first part of a two articles series:
  1. Sitecore.Demo.Shared NuGet Packages Explained
  2. Consuming Sitecore.Demo.Shared NuGet Packages
The Sitecore.Demo.Shared repository hosts Helix modules that are consumed and used by multiple Sitecore demo sites like:
There are many advantages of separating these modules in a separate repository:
  • Code reuse across websites.
  • Consistent user experience across websites.
  • Quicker development of new websites.
There are also some disadvantages of this architecture:
  • As the modules are used in SXA and non-SXA websites, front-end assets cannot be in the shared module. They must be duplicated in the respective websites.
  • Changes in a shared module might require changes in the consuming websites at the same time. When working on a specific site, developers must make sure that all consuming websites are adapted at the same time.

Distribution

Each Helix module in the repository is distributed as a NuGet package in the Sitecore demo packages feed: https://sitecore.myget.org/F/sc-demo-packages/api/v3/index.json
The feed is hidden, and its packages cannot be listed.
 
In the repository, each module has a matching .nuspec file in the \Build\nuspec folder. The files in this folder represent the list of available NuGet packages. The Sitecore demo team publishes new versions of the packages when changes are made to the repository files.
 
The packages version number is using semantic versioning.
 
For Sitecore 9.2 and older, a Sitecore.Demo.Shared package version number "9.2.0.63" means:
  • 9: Sitecore major version the package is compatible with.
  • 2: Sitecore minor version the package is compatible with.
  • 0: Sitecore update version the package is compatible with.
  • 63: `Sitecore.Demo.Shared` incremental build number.

Thus, the "9.2.0.63" version of the packages are only compatible with Sitecore 9.2 initial release (update-0).

This versioning format did not allow for introducing breaking changes in the content of the package. Thus, from Sitecore 9.3, the Sitecore.Demo.Shared packages version number changed to a different format where "930.1.2" means:

  • 930: Sitecore major, minor, and update version the package is compatible with. "930" is for Sitecore 9.3 update-0.
  • 1: Sitecore.Demo.Shared major version. Increased when breaking changes are introduced.
  • 2: Sitecore.Demo.Shared incremental build number. Increased by continuous integration scripts when non-breaking changes are introduced.

Thus, the "930.1.2" version of the packages are only compatible with Sitecore 9.3 initial release (update-0).

This allows referencing the Sitecore.Demo.Shared packages with a wildcard like "930.1.*" to get the latest version that is not introducing breaking changes.

Packages Content

Each NuGet package contains an assembly for the Helix module. The assembly name format is Sitecore.Demo.[Layer].[Module]. Most of the packages also contains some or all of these content files:
  • Configuration files.
  • Views.
  • Serialized Unicorn items.
  • A custom .targets file that copies some content files after each build of the project referencing the package.

Unicorn Items

Location

In the Sitecore.Demo.Shared repository, Unicorn items are located in the default \src\[Layer]\[Module]\serialization Helix convention location.

Due to recent efforts to run the Sitecore demos on Docker, Unicorn items location in other demo repositories has recently changed from \src\[Layer]\[Module]\serialization to \items\[Layer]\[Module]. This was done to mount a single volume in Docker containers for all the Unicorn items and nothing else.

The .targets file included in Sitecore.Demo.Shared NuGet packages is copying the Unicorn items in \items\Shared\[Layer]\[Module] after each build of the project referencing the package. The items are inside a \Shared subfolder to avoid a collision in Helix module names between Sitecore.Demo.Shared and the consuming solution. The .targets file also copies a .gitignore file to that folder for the copied Unicorn items to be excluded from Git source control.

Configuration

Installing this package also deploys the following Unicorn configuration file to your Sitecore web root:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
               xmlns:role="http://www.sitecore.net/xmlconfig/role/"
               xmlns:unicorn="http://www.sitecore.net/xmlconfig/unicorn/">
  <sitecore unicorn:require="On">
    <unicorn>
      <configurations>
        <configuration name="Feature.Demo" description="Feature Demo" dependencies="Foundation.*" extends="Helix.Feature">
          <targetDataStore physicalRootPath="$(sourceFolder)\Shared\Feature\Demo" useDataCache="false" singleInstance="true" />
          <predicate type="Unicorn.Predicates.SerializationPresetPredicate, Unicorn" singleInstance="true">
            <include name="Layouts" database="master" path="/sitecore/layout/Layouts/Feature/Habitat Home/Demo" />
            <include name="Renderings" database="master" path="/sitecore/layout/Renderings/Feature/Habitat Home/Demo" />
            <include name="Templates" database="master" path="/sitecore/templates/Feature/Habitat Home/Demo" />
          </predicate>
        </configuration>
      </configurations>
    </unicorn>
  </sitecore>
</configuration>

The configuration is only active if the unicorn:define appSetting is set to On. It also uses the $(sourceFolder) Sitecore variable for its path.

Conclusion

I hope this article helped you understand how the Sitecore demo team NuGet packages from a separate repository are working. Continue reading the Consuming Sitecore.Demo.Shared NuGet Packages article to learn how to consume one or more of the packages in your own solution.
 
For any question, you can reach the Sitecore demo team on the #habitathome channel of the Sitecore Slack community.