This guide shows how a custom xConnect model is included when building your Sitecore Docker images for a Sitecore Experience Platform (XP) implementation.
Before you begin
Clone the Docker Examples repository
If you haven't already done so, clone the Docker Examples repository to a location on your machine. For example, C:\sitecore\docker-examples\ (this article will assume this folder has been used).
This repository includes companion code for the Sitecore Containers DevEx documentation. For this guide, you'll use the custom-images folder.
The custom-images example requires some preparation before it can be run. If you have not already done so, either follow the preparation steps or run the included
init.ps1 script to perform these preparation steps automatically.
Open a PowerShell administrator prompt and navigate to the custom-images folder (e.g. C:\sitecore\docker-examples\custom-images). Run the following command, replacing the
-LicenseXmlPath with the location of your Sitecore license file.
.\init.ps1 -LicenseXmlPath C:\License\license.xml
Understand xConnect model deployment
There are several required build artifacts involved with xConnect custom model development, each of which needs to end up in specific images within the Sitecore Experience Platform container environment.
Build artifacts defined
Based on the documentation for creating and deploying custom xConnect models, you'll have the following hypothetical build artifacts coming out of this.
- CustomModel, 1.0.json
- sc.CustomModel.xml (step 2 in the documentation Deploy the model to the Marketing Automation Engine section)
- Sitecore.XConnect.Client.config patch (step 2 in the documentation Deploy the model to core roles section)
Sitecore images requiring artifacts
The table below lists Sitecore images for both XP0 (Single) and XP1 (Scaled) topologies. You can see which images require the xConnect build artifacts and where they must be included. If an image is not listed here, it does not require any artifacts.
The inclusion of these artifacts will take place in your Sitecore runtime Dockerfile for each image / role.
|Sitecore image / role||XP0||XP1||CustomModel.dll||CustomModel, 1.0.json||sc.CustomModel.xml||Sitecore.XConnect.Client.config patch|
rootpath varies per image:
C:\servicefor the "worker" roles,
C:\inetpub\wwwrootfor all others.
The Docker Examples xConnect projects
The Docker Examples repository includes multiple projects to help demonstrate a custom xConnect model. Navigate to the custom-images folder and open the solution DockerExamples.sln in Visual Studio. Take a look at the following projects.
- DockerExamples.XConnect.Model - Contains a custom xConnect model and facet (CustomModel.dll in the table above).
- DockerExamples.XConnect - Facilitates the build and publish of xConnect artifacts and also includes required xConnect config files
DockerExamples.XConnect.Model.DemoModel, 1.0.json(CustomModel, 1.0.json in the table above) and
sc.DockerExamples.DemoModel.xml(sc.CustomModel.xml in the table above).
- DockerExamples.Website - Facilitates the build and publish of website/platform artifacts and also includes required xConnect config file
DockerExamples.XConnect.config(Sitecore.XConnect.Client.config patch in the table above).
In a Helix solution, the DockerExamples.XConnect and DockerExamples.Website projects would likely be broken out into separate Environment modules and one or more Project/Feature modules, but are combined for simplicity here.
- App.XConnect.ModelBuilder - A console app used to generate the required xConnect model JSON file.
- App.XConnect.Demo - A console app which adds a test contact with our custom model and facet.
Configure in solution build
Navigate to the custom-images folder, and review the
Dockerfile located here (e.g. C:\sitecore\docker-examples\custom-images\Dockerfile).
You'll see xConnect (DockerExamples.XConnect.csproj) is built separately from the website/platform build (DockerExamples.Website.csproj), with the output landing at
RUN msbuild .\src\DockerExamples.XConnect\DockerExamples.XConnect.csproj /p:Configuration=Release /p:DeployOnBuild=True /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishUrl=C:\out\xconnect
You'll then see these copied in from the
builder stage to the final image with the following structure:
COPY --from=builder C:\out\xconnect .\xconnect\
Alternative - dynamically generate xConnect model JSON files
Instead of generating the model JSON manually (e.g. using App.XConnect.ModelBuilder) and including in the solution (\src\DockerExamples.XConnect\App_Data\Models\DockerExamples.XConnect.Model.DemoModel, 1.0.json), you could do this as part of the Dockerfile instructions.
The one noted drawback with this approach is that you won't be able to publish your xConnect model into a running container (since an image build is required).
The App.XConnect.ModelBuilder example accepts an argument for the output path. Within the
builder stage, you could build the App.XConnect.ModelBuilder, and then use it to generate xConnect model JSON files.
RUN msbuild .\src\App.XConnect.ModelBuilder\App.XConnect.ModelBuilder.csproj /p:Configuration=Release /p:OutDir=C:\build RUN .\App.XConnect.ModelBuilder C:\out\xconnect\models
Then adjust your final artifact instructions to copy these in.
COPY --from=builder C:\out\xconnect .\xconnect\ COPY --from=builder C:\out\xconnect\models .\xconnect\App_Data\Models\
Add artifacts to Sitecore runtime images
The following example will show you the configuration for a Sitecore Experience Platform - Single (XP0) topology.
You must also consider setting up the Sitecore runtime images for services within Sitecore Experience Platform - Scaled (XP1) if you plan on deploying to that topology in an upstream environment. The Docker Examples repository has example Sitecore runtime Dockerfiles for these services as well (xdbcollection, xdbsearch, etc).
Open the Sitecore runtime Dockerfile for the xconnect service (e.g. C:\sitecore\docker-examples\custom-images\docker\build\xconnect\Dockerfile).
Since this uses an IIS image,
C:\inetpub\wwwroot is set to the working directory, and then the xConnect build files from the
solution build image are copied in.
WORKDIR C:\inetpub\wwwroot COPY --from=solution \artifacts\xconnect\ .\
Now open the Sitecore runtime Dockerfile for the xdbsearchworker service (e.g. C:\sitecore\docker-examples\custom-images\docker\build\xdbsearchworker\Dockerfile).
The xConnect worker roles are .NET Core, and thus a different working directory of
C:\service is used.
Now, if you look at the table above, you'll notice the worker roles are a bit more selective in which artifacts are included. The xdbsearchworker image only requires the model JSON file.
COPY --from=solution \artifacts\xconnect\App_Data\Models\ .\App_Data\Models\
However, the xdbautomationworker (e.g. C:\sitecore\docker-examples\custom-images\docker\build\xdbautomationworker\Dockerfile) requires the model assembly and the xml file.
COPY --from=solution \artifacts\xconnect\bin\ .\ COPY --from=solution \artifacts\xconnect\App_Data\Config\Sitecore\MarketingAutomation\ .\App_Data\Config\Sitecore\MarketingAutomation\
While the cortexprocessingworker (e.g. C:\sitecore\docker-examples\custom-images\docker\build\cortexprocessingworker\Dockerfile) requires the model assembly and the JSON file.
COPY --from=solution \artifacts\xconnect\bin\ .\ COPY --from=solution \artifacts\xconnect\App_Data\Models\ .\App_Data\Models\
Run Docker Examples
Ensure you have completed the required example preparation.
Open a PowerShell prompt and navigate to the custom-images folder (e.g. C:\sitecore\docker-examples\custom-images) . Run Docker Examples using the Docker Compose
docker-compose up -d
For a quick reference of this and other common commands used in the guides, see the Sitecore Docker cheat sheet.
Once the instance is up and running, go back to Visual Studio and run the App.XConnect.Demo console application. This will add a test contact which uses the custom model (
DemoModel) and facet (
You can verify the contact was added with our custom facet by connecting to SQL Server and retrieving records from
When you're done, stop and remove the containers using the