Merge pull request #52 from Avanade/v3.0.0

v3.0.0
Avanade · Nov 21, 2024 · a6477a0 · a6477a0
2 parents 5cd46db + 3b94099
commit a6477a0
Show file tree

Hide file tree

Showing 204 changed files with 8,407 additions and 2,979 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -18,9 +18,8 @@ jobs:
       uses: actions/setup-dotnet@v1
       with:
         dotnet-version: |
-            6.0.x
-            7.0.x
             8.0.x
+            9.0.x
         
     - name: Restore dependencies
       run: dotnet restore
@@ -44,7 +43,10 @@ jobs:
       run: sleep 10
 
     - name: Set EnvVar for Test
-      run: echo "SqlServerDemo_ConnectionStrings__SqlDb=Data Source=localhost, 1433;Initial Catalog=NTangleDemo;User id=sa;Password=yourStrong(!)Password;TrustServerCertificate=true" >> $GITHUB_ENV
+      run: |
+          echo "SqlServerDemo_ConnectionStrings__SqlDb=Data Source=localhost, 1433;Initial Catalog=NTangleDemo;User id=sa;Password=yourStrong(!)Password;TrustServerCertificate=true" >> $GITHUB_ENV
+          echo "SqlServerSidecarDemo_ConnectionStrings__SqlDb=Data Source=localhost, 1433;Initial Catalog=NTangleDemo_Main;User id=sa;Password=yourStrong(!)Password;TrustServerCertificate=true" >> $GITHUB_ENV
+          echo "SqlServerSidecarDemo_ConnectionStrings__SidecarDb=Data Source=localhost, 1433;Initial Catalog=NTangleDemo_Sidecar;User id=sa;Password=yourStrong(!)Password;TrustServerCertificate=true" >> $GITHUB_ENV
 
     - name: Test
       run: dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=lcov /p:CoverletOutput=./coverage/lcov.info --no-build --verbosity normal

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,20 @@
 
 Represents the **NuGet** versions.
 
+## v3.0.0
+- *Enhancement:* Major **"Sidecar"** feature added based on feedback from the community. 
+  - The existing implementation required all generated supporting database capabilities to be within the "source" database itself; a new option has been added to generate a separate "sidecar" database to manage. This minimizes the impact on the "source" database.
+  - The "source" database will still require the database CDC (change-data-capture) capabilities to be enabled.
+  - The new [`EntitySidecarOrchestratorBase`](./src/NTangle/Cdc/EntitySidecarOrchestratorBase.cs) will invoke a single statement to leverage the CDC capabilities and perform the resulting data selection; see the [`ContactExecuteBatch.sql`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.Publisher/Resources/Generated/ContactExecuteBatch.sql).
+  - The required `NTangle` (and optional `Outbox`) schema(s), table(s) and stored procedures will be generated within the "sidecar" database.
+  - Note that there are _no_ cross database dependencies; as such, the "sidecar" database can be hosted separately, be on a difference versions, etc. as required. The .NET orchestrator logic will _require_ access to both databases to function.
+  - An additional `ExecuteExplicitAsync` method has been added to enable explicit primary keys to be passed bypassing CDC; useful for one-offs, or where triggering without CDC (i.e. Debezium, etc) to get the best of both worlds.
+  - Support now for `net8.0`+ only; older .NET versions will need to use the existing implementation or upgrade.
+- Notes:
+  - This version contains a number of _breaking_ and generated artefact changes; all existing generated artefacts should re-generated.
+  - It is recommended migrating to the new "sidecar" feature where possible; the existing implementation will be deprecated in the future.
+	- The `NTangle` solution template (`dotnet new ntangle`) has been updated to default to the new "sidecar" feature.
+
 ## v2.6.1
 - *Fixed:* As a result of the `v2.6.0` enhancements the generated `IdentifierMappingMapper.cs` and `VersionTrackingMapper.cs` are not required. This fix will ensure these files are no longer generated; as such these should be removed from any existing solution after a re-gen.
 - *Fixed:* The base `EntityOrchestrator` classes have also been corrected to remove the `IdentifierMappingMapper` and `VersionTrackingMapper` references.

diff --git a/Common.targets b/Common.targets
@@ -1,6 +1,6 @@
 <Project>
   <PropertyGroup>
-    <Version>2.6.1</Version>
+    <Version>3.0.0</Version>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <Authors>NTangle Developers</Authors>
     <Company>Avanade</Company>

diff --git a/NTangle.sln b/NTangle.sln
@@ -65,33 +65,19 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Github Actions", "Github Ac
 		.github\workflows\CI.yml = .github\workflows\CI.yml
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ContactSync", "ContactSync", "{240EFA31-7366-47BD-8A56-B3312D06BB13}"
-	ProjectSection(SolutionItems) = preProject
-		samples\ContactSync\README.md = samples\ContactSync\README.md
-	EndProjectSection
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "OldApp", "OldApp", "{1FF28F16-F241-4EA0-9DD1-81E19C6A7EF5}"
-EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.OldApp.CodeGen", "samples\ContactSync\ContactSync.OldApp\ContactSync.OldApp.CodeGen\ContactSync.OldApp.CodeGen.csproj", "{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NTangle.CodeGen", "tools\NTangle.CodeGen\NTangle.CodeGen.csproj", "{BB87378A-0444-4BDC-8530-20F25D852C77}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.OldApp.Database", "samples\ContactSync\ContactSync.OldApp\ContactSync.OldApp.Database\ContactSync.OldApp.Database.csproj", "{4C20E9BE-2C69-419A-A775-75A11A707E63}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SqlServerSidecarDemo", "SqlServerSidecarDemo", "{12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.OldApp.Publisher", "samples\ContactSync\ContactSync.OldApp\ContactSync.OldApp.Publisher\ContactSync.OldApp.Publisher.csproj", "{F48B08F9-57A5-405D-B40B-2D672A10CD5C}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SqlServerSidecarDemo.CodeGen", "samples\SqlServerSidecarDemo\SqlServerSidecarDemo.CodeGen\SqlServerSidecarDemo.CodeGen.csproj", "{C51EA07D-D813-405D-B80E-D2F9817BCE5F}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "NewApp", "NewApp", "{6855FFC2-39E7-48D4-AB5D-079D406390FC}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SqlServerSidecarDemo.Database", "samples\SqlServerSidecarDemo\SqlServerSidecarDemo.Database\SqlServerSidecarDemo.Database.csproj", "{7B512BDD-724B-4DDE-9211-A20EBCFDC96A}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.NewApp.Database", "samples\ContactSync\ContactSync.NewApp\ContactSync.NewApp.Database\ContactSync.NewApp.Database.csproj", "{4BADE51C-EA1C-4A68-B591-8F148F5FF975}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SqlServerSidecarDemo.SidecarDb", "samples\SqlServerSidecarDemo\SqlServerSidecarDemo.SidecarDb\SqlServerSidecarDemo.SidecarDb.csproj", "{87E20413-B5DF-4E6C-904B-2DAE0DF65C11}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.NewApp.Subscriber", "samples\ContactSync\ContactSync.NewApp\ContactSync.NewApp.Subscriber\ContactSync.NewApp.Subscriber.csproj", "{D6364CFB-DAAA-41E7-996F-8F1654EECF10}"
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7596959A-8A5E-409D-BED5-006950299A4E}"
-	ProjectSection(SolutionItems) = preProject
-		samples\ContactSync\docs\old-app-code-gen.md = samples\ContactSync\docs\old-app-code-gen.md
-		samples\ContactSync\docs\old-app-publish.md = samples\ContactSync\docs\old-app-publish.md
-		samples\ContactSync\docs\old-app-setup.md = samples\ContactSync\docs\old-app-setup.md
-	EndProjectSection
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SqlServerSidecarDemo.Publisher", "samples\SqlServerSidecarDemo\SqlServerSidecarDemo.Publisher\SqlServerSidecarDemo.Publisher.csproj", "{0E8663F4-EDA1-42A9-BDF5-085D230A784A}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NTangle.CodeGen", "tools\NTangle.CodeGen\NTangle.CodeGen.csproj", "{BB87378A-0444-4BDC-8530-20F25D852C77}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SqlServerSidecarDemo.Test", "samples\SqlServerSidecarDemo\SqlServerSidecarDemo.Test\SqlServerSidecarDemo.Test.csproj", "{3707977E-BC42-4CBA-9432-7F41F2BEE8F9}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -131,30 +117,30 @@ Global
 		{467C4732-8A67-435C-9AB4-697CB89C4EE4}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{467C4732-8A67-435C-9AB4-697CB89C4EE4}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{467C4732-8A67-435C-9AB4-697CB89C4EE4}.Release|Any CPU.Build.0 = Release|Any CPU
-		{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488}.Release|Any CPU.Build.0 = Release|Any CPU
-		{4C20E9BE-2C69-419A-A775-75A11A707E63}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{4C20E9BE-2C69-419A-A775-75A11A707E63}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{4C20E9BE-2C69-419A-A775-75A11A707E63}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{4C20E9BE-2C69-419A-A775-75A11A707E63}.Release|Any CPU.Build.0 = Release|Any CPU
-		{F48B08F9-57A5-405D-B40B-2D672A10CD5C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{F48B08F9-57A5-405D-B40B-2D672A10CD5C}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{F48B08F9-57A5-405D-B40B-2D672A10CD5C}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{F48B08F9-57A5-405D-B40B-2D672A10CD5C}.Release|Any CPU.Build.0 = Release|Any CPU
-		{4BADE51C-EA1C-4A68-B591-8F148F5FF975}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{4BADE51C-EA1C-4A68-B591-8F148F5FF975}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{4BADE51C-EA1C-4A68-B591-8F148F5FF975}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{4BADE51C-EA1C-4A68-B591-8F148F5FF975}.Release|Any CPU.Build.0 = Release|Any CPU
-		{D6364CFB-DAAA-41E7-996F-8F1654EECF10}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{D6364CFB-DAAA-41E7-996F-8F1654EECF10}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{D6364CFB-DAAA-41E7-996F-8F1654EECF10}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{D6364CFB-DAAA-41E7-996F-8F1654EECF10}.Release|Any CPU.Build.0 = Release|Any CPU
 		{BB87378A-0444-4BDC-8530-20F25D852C77}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{BB87378A-0444-4BDC-8530-20F25D852C77}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{BB87378A-0444-4BDC-8530-20F25D852C77}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{BB87378A-0444-4BDC-8530-20F25D852C77}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C51EA07D-D813-405D-B80E-D2F9817BCE5F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C51EA07D-D813-405D-B80E-D2F9817BCE5F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C51EA07D-D813-405D-B80E-D2F9817BCE5F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C51EA07D-D813-405D-B80E-D2F9817BCE5F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7B512BDD-724B-4DDE-9211-A20EBCFDC96A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7B512BDD-724B-4DDE-9211-A20EBCFDC96A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7B512BDD-724B-4DDE-9211-A20EBCFDC96A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7B512BDD-724B-4DDE-9211-A20EBCFDC96A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{87E20413-B5DF-4E6C-904B-2DAE0DF65C11}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{87E20413-B5DF-4E6C-904B-2DAE0DF65C11}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{87E20413-B5DF-4E6C-904B-2DAE0DF65C11}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{87E20413-B5DF-4E6C-904B-2DAE0DF65C11}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0E8663F4-EDA1-42A9-BDF5-085D230A784A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0E8663F4-EDA1-42A9-BDF5-085D230A784A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0E8663F4-EDA1-42A9-BDF5-085D230A784A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0E8663F4-EDA1-42A9-BDF5-085D230A784A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3707977E-BC42-4CBA-9432-7F41F2BEE8F9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3707977E-BC42-4CBA-9432-7F41F2BEE8F9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3707977E-BC42-4CBA-9432-7F41F2BEE8F9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3707977E-BC42-4CBA-9432-7F41F2BEE8F9}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -169,16 +155,13 @@ Global
 		{54D9318B-8D30-41FF-A5DD-554C13AC62F3} = {5B2FCA11-CC69-40D7-9FC3-DC7707C77D45}
 		{AD6A38DA-9BB6-4650-A512-434EC19E8DDD} = {780B69CA-D467-45CF-B115-A3FEB0B88BD1}
 		{467C4732-8A67-435C-9AB4-697CB89C4EE4} = {54E2D3C7-1AC1-4EA6-A8CA-42EC12A6E299}
-		{240EFA31-7366-47BD-8A56-B3312D06BB13} = {3A0B49DA-7D84-4B96-A4F3-FAF77C3E2FB3}
-		{1FF28F16-F241-4EA0-9DD1-81E19C6A7EF5} = {240EFA31-7366-47BD-8A56-B3312D06BB13}
-		{9A1DDC23-4B62-43F6-8C4E-D5CB86E5D488} = {1FF28F16-F241-4EA0-9DD1-81E19C6A7EF5}
-		{4C20E9BE-2C69-419A-A775-75A11A707E63} = {1FF28F16-F241-4EA0-9DD1-81E19C6A7EF5}
-		{F48B08F9-57A5-405D-B40B-2D672A10CD5C} = {1FF28F16-F241-4EA0-9DD1-81E19C6A7EF5}
-		{6855FFC2-39E7-48D4-AB5D-079D406390FC} = {240EFA31-7366-47BD-8A56-B3312D06BB13}
-		{4BADE51C-EA1C-4A68-B591-8F148F5FF975} = {6855FFC2-39E7-48D4-AB5D-079D406390FC}
-		{D6364CFB-DAAA-41E7-996F-8F1654EECF10} = {6855FFC2-39E7-48D4-AB5D-079D406390FC}
-		{7596959A-8A5E-409D-BED5-006950299A4E} = {240EFA31-7366-47BD-8A56-B3312D06BB13}
 		{BB87378A-0444-4BDC-8530-20F25D852C77} = {780B69CA-D467-45CF-B115-A3FEB0B88BD1}
+		{12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB} = {3A0B49DA-7D84-4B96-A4F3-FAF77C3E2FB3}
+		{C51EA07D-D813-405D-B80E-D2F9817BCE5F} = {12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}
+		{7B512BDD-724B-4DDE-9211-A20EBCFDC96A} = {12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}
+		{87E20413-B5DF-4E6C-904B-2DAE0DF65C11} = {12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}
+		{0E8663F4-EDA1-42A9-BDF5-085D230A784A} = {12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}
+		{3707977E-BC42-4CBA-9432-7F41F2BEE8F9} = {12BF3E9B-E59B-45AC-B307-7B68BD8B6DFB}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {B97E5639-3430-4AD7-9942-D35EF26F263B}

diff --git a/README.md b/README.md
@@ -16,6 +16,16 @@ This has a key advantage of being an excellent candidate within event-streaming
 
 <br/>
 
+## Sidecar database
+
+As of version `3.0.0` the preferred (recommended and default) approach is to use a sidecar database to manage the _nTangle_ runtime artefacts. This is to ensure that the main database is not polluted with the _nTangle_ specific artefacts, and to ensure that the _nTangle_ runtime can be easily removed without impacting the main database.
+
+Usage of a sidecar database will also limit impact (load and data) on the main database by minimizing access to required CDC and related data selection only. The required orchestration will occur against the sidecar database.
+
+Note that there are no cross database dependencies; as such, the sidecar database can be hosted separately, be on a different version, etc. as required. The .NET orchestrator logic _will_ require access to both databases to function.
+
+<br/>
+
 ## Demonstration
 
 The following video provides a high-level demonstration of _nTangle_ and its capabilities.
@@ -46,7 +56,7 @@ SalesOrder             // Parent
 ``` 
 
 The CDC capability is used specifically as a trigger for change (being `Create`, `Update` or `Delete`). The resulting data that is published is the latest, not a snapshot in time (CDC captured). The reason for this is two-fold:
-1. Given how the CDC data is batch retrieved there is no guarantee that the CDC captured data represents a final intended state suitable for publishing; and,
+1. Given how the CDC data is batch retrieved there is no guarantee that the CDC captured data represents a final intended state (transactionally consistent) suitable for publishing; and,
 2. This process is intended to be running near real-time so getting the latest version will produce the most current committed version as at that time.
 
 To further guarantee only a single event for a specific version is published the resulting _entity_ is JSON serialized and hashed; this value is checked (and saved) against the prior version to ensure a publish contains data that is actionable. This will minimize redundant publishing, whilst also making the underlying processing more efficient.
@@ -103,9 +113,9 @@ Documentation related to each of the above are as follows:
 - [`JoinMapping`](./docs/generated/joinmapping.md) - defines global identifier mappings for any of the join table columns.
 - [`TableMapping`](./docs/generated/tablemapping.md) - defines global identifier mappings for any of the primary table columns.
 
-An example [ntangle.yaml](./samples/SqlServerDemo/SqlServerDemo.CodeGen/ntangle.yaml) configuration file exists within the [`SqlServerDemo`](./samples/SqlServerDemo) sample. The [`SqlServerDemo.CodeGen`](./samples/SqlServerDemo/SqlServerDemo.CodeGen) sample also demonstrates how to invoke the code generator from the underlying [`Program`](./samples/SqlServerDemo/SqlServerDemo.CodeGen/Program.cs).
+An example [ntangle.yaml](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.CodeGen/ntangle.yaml) configuration file exists within the [`SqlServerSidecarDemo`](./samples/SqlServerSidecarDemo) sample. The [`SqlServerSidecarDemo.CodeGen`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.CodeGen) sample also demonstrates how to invoke the code generator from the underlying [`Program`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.CodeGen/Program.cs).
 
-The code-generator will output a number of generated artefacts; these will be either database-related (see [`SqlServerDemo.Database`](./samples/SqlServerDemo/SqlServerDemo.Database) sample) or corresponding .NET runtime components (see [`SqlServerDemo.Publisher`](./samples/SqlServerDemo/SqlServerDemo.Publisher) sample).
+The code-generator will output a number of generated artefacts; these will be either database-related (see [`SqlServerSidecarDemo.Database`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.SidecarDb) sample) or corresponding .NET runtime components (see [`SqlServerSidecarDemo.Publisher`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.Publisher) sample).
 
 The following [`NTangle`](./src/NTangle) namespaces provide the code-generation capabilties:
 
@@ -119,7 +129,7 @@ Namespace | Description
 
 ### Runtime
 
-Generally, a runtime publisher is required to orchestrate the CDC-triggered aggregated entity publishing process (see [`SqlServerDemo.Publisher`](./samples/SqlServerDemo/SqlServerDemo.Publisher) sample). This in turn takes a dependency on the _nTangle_ runtime to enable.
+Generally, a runtime publisher is required to orchestrate the CDC-triggered aggregated entity publishing process (see [`SqlServerSidecarDemo.Publisher`](./samples/SqlServerSidecarDemo/SqlServerSidecarDemo.Publisher) sample). This in turn takes a dependency on the _nTangle_ runtime to enable.
 
 The following [`NTangle`](./src/NTangle) namespaces provide the runtime capabilties:
 
@@ -146,7 +156,10 @@ The following samples are provided to guide usage:
 
 Sample | Description
 -|-
-[`SqlServerDemo`](./samples/SqlServerDemo) | A sample as an end-to-end solution to demonstrate the usage of _nTangle_ against a Microsoft SQL Server database. However, the best place to follow along and learn is to use the [`NTangle.Template`](./tools/NTangle.Template) tool - instructions are within to guide end-to-end setup and execution.
+[`SqlServerSidecarDemo`](./samples/SqlServerSidecarDemo) | A sample as an end-to-end solution to demonstrate the usage of _nTangle_ against a Microsoft SQL Server database leveraging a _sidecar_ database. This is the preferred and default approach to use _nTangle_.
+[`SqlServerDemo`](./samples/SqlServerDemo) | A sample as an end-to-end solution to demonstrate the usage of _nTangle_ against a single Microsoft SQL Server database. This is the legacy approach to use _nTangle_.
+
+However, the best place to follow along and learn is to use the [`NTangle.Template`](./tools/NTangle.Template) tool - instructions are within to guide end-to-end setup and execution.
 
 <br/>