---
title: "Including a custom xConnect model"
slug: "including-a-custom-xconnect-model"
abstract: "Include a custom xConnect model when you build Sitecore Docker images."
---
# Including a custom xConnect model

This topic explains how you include a custom xConnect model when you build Sitecore Docker images for a Sitecore Experience Platform (XP) implementation. Additionally, this guide assumes you have some knowledge of Sitecore xConnect, the xConnect model, and how customizations are made.

<details>
<summary><h2>Clone the Docker Examples repository</h2></summary>

If you have not already done so, clone the [Docker Examples repository](https://github.com/Sitecore/docker-examples) to a location on your machine. This topic uses the *custom-images* folder from the repository.

</details>

<details>
<summary><h2>Example preparation</h2></summary>

The *custom-images* example requires some preparation before it can be run. If you have not already done so, either follow the [preparation steps](https://doc.sitecore.com/xp/en/developers/102/developer-tools/run-sitecore.md#preparation) or run the included `init.ps1` script to perform these preparation steps automatically:

- Open a PowerShell administrator prompt, navigate to the *custom-images* folder, and run the following command, replacing the `-LicenseXmlPath` with the location of your Sitecore license file:

    ```text
    .\init.ps1 -LicenseXmlPath C:\License\license.xml
    ```

</details>

<details>
<summary><h2>Understand xConnect model deployment</h2></summary>

xConnect custom model development requires several build artifacts, and you must make sure that each of these artifacts are included in specific images within the Sitecore Experience Platform container environment.

### Build artifacts defined

Based on the documentation for creating and deploying custom xConnect models, there are the following (hypothetical) build artifacts:

- `CustomModel.dll`
- `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 that requite artifacts

The following table lists Sitecore images for both XP0 (Single) and XP1 (Scaled) topologies. You can see which images require the xConnect build artifacts and where you must included them. If an image is not listed here, it does not require any artifacts.

You include these artifacts 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 |
| --- | --- | --- | --- | --- | --- | --- |
| cd |  | x | `root`\bin |  |  | x |
| cm | x | x | `root`\bin |  |  | x |
| xconnect | x |  | `root`\bin | `root`\App_Data\Models | `root`\App_Data\Config\Sitecore\MarketingAutomation |  |
| xdbsearchworker | x | x |  | `root`\App_Data\Models |  |  |
| xdbautomationworker | x | x | `root` |  | `root`\App_Data\Config\Sitecore\MarketingAutomation |  |
| cortexprocessingworker | x | x | `root` | `root`\App_Data\Models |  |  |
| prc |  | x | `root`\bin |  |  | x |
| xdbcollection |  | x | `root`\bin | `root`\App_Data\Models |  |  |
| xdbsearch |  | x | `root`\bin | `root`\App_Data\Models |  |  |
| xdbautomation |  | x | `root`\bin | `root`\App_Data\Models | `root`\App_Data\Config\Sitecore\MarketingAutomation |  |

Note the `root` path varies for each image: `C:\service` for the worker roles, `C:\inetpub\wwwroot` for all others.

</details>

<details>
<summary><h2>The Docker Examples xConnect projects</h2></summary>

The Docker Examples repository has multiple projects that demonstrate custom xConnect models. Navigate to the *custom-images* folder and open the solution *DockerExamples**.sln* in Visual Studio. The solution includes these 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 the required xConnect config files `DockerExamples.XConnect.Model.DemoModel, 1.0.json` (*CustomModel, 1.0.json* in the previous table), and `sc.DockerExamples.DemoModel.xml` (*sc.CustomModel.xml* in the previous table).
- *DockerExamples.Website*: Facilitates the build and publish of website/platform artifacts, and also includes the required xConnect config file `DockerExamples.XConnect.config` (*Sitecore.XConnect.Client.config patch* in the previous table).
- `App.XConnect.ModelBuilder`: A console app you use to generate the required xConnect model JSON file.
- *App.XConnect.Demo*: A console app that adds a test contact with the custom model and facet.

In a [Helix solution](https://helix.sitecore.net/), the *DockerExamples.XConnect* and *DockerExamples.Website* projects are most often broken down into separate Environment modules and one or more project/feature modules. They are combined here for the sake of simplicity.

</details>

<details>
<summary><h2>Configuring in solution build</h2></summary>

To see how the solution is configured in the Docker Examples:

1. Open the`Dockerfile` in the *custom-images* folder. It shows that the xConnect project (*DockerExamples.XConnect.csproj*) is built separately from the website/platform build (*DockerExamples.Website.csproj*), with the output at `C:\out\xconnect`:

    ```text
    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
    ```

2. Copy in from the `builder` stage to the final image with the following structure:
    - *\\artifacts\\xconnect*:

    ```text
    COPY --from=builder C:\out\xconnect .\xconnect\
    ```

### Alternative: Generate xConnect model JSON files dynamically

Instead of generating the model JSON manually (for example, by using *App.XConnect.ModelBuilder*) and including it in the solution (*\\src\\DockerExamples.XConnect\\App_Data\\Models\\DockerExamples.XConnect.Model.DemoModel, 1.0.json*), you can do this as part of the Dockerfile instructions. The drawback of this is that you cannot publish your xConnect model into a running container because this requires an image build.

The *App.XConnect.ModelBuilder* example accepts an argument for the output path. Within the `builder` stage, you can 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

```

You must 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\

```

</details>

<details>
<summary><h2>Add artifacts to Sitecore runtime images</h2></summary>

The following example shows the configuration for a *Sitecore Experience Platform - Single (XP0)* topology.

> [!note]
> 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*, and so on).

To see this example:

1. Open the [Sitecore runtime Dockerfile](https://doc.sitecore.com/xp/en/developers/102/developer-tools/build-sitecore-images.md#sitecore-runtime-dockerfiles) for the *xconnect* service (for example, `C:\sitecore\docker-examples\custom-images\docker\build\xconnect\Dockerfile`).
2. Because 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\ .\
    ```

3. Open the Sitecore runtime Dockerfile for the *xdbsearchworker* service. The xConnect worker roles are .NET Core, and therefore a different working directory of `C:\service` is used:

    ```text
    WORKDIR C:\service
    ```

    If you look at the previous table, you can see the worker roles are more selective about which artifacts are included. The *xdbsearchworker* image only requires the model JSON file:

    ```text
    COPY --from=solution \artifacts\xconnect\App_Data\Models\ .\App_Data\Models\
    ```

    However, the *xdbautomationworker* 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* 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\
    ```

</details>

<details>
<summary><h2>Run Docker Examples</h2></summary>

To run the Docker Examples:

1. Open a PowerShell prompt, go to the *custom-images* folder, and run Docker Examples with the Docker Compose `up` command:

    ```text
    docker-compose up -d
    ```

2. When the instance is up and running, go back to Visual Studio and run the *App.XConnect.Demo* console application. This adds a test contact that uses the custom model (`DemoModel`) and facet (`DemoFacet`).

    You can verify the contact was added with the custom facet by connecting to SQL Server and retrieving records from `[Sitecore.Xdb.Collection.Shard0/1].[xdb_collection].[ContactFacets]`:

    ![Docker-Examples-XConnect-Model.png](https://doc.sitecore.com/api/markdown-image/xp/en/developers/102/developer-tools/images/Docker-Examples-XConnect-Model.png)

3. Stop and remove the containers with the `down` command:

    ```text
    docker-compose down
    ```

</details>