Merge pull request #35 from Avanade/v2.2.0

v2.2.0

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Represents the **NuGet** versions.
 
+## v2.2.0
+- *Enhancement:* Added `publisher` option with values `Console|Function|None`, where `Console` is the default, and `Function` represents [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/functions-overview), for the `NTangle.Template` package.
+- *Fixed:* The `IdentifierMappingMapper.cs` file was incorrrectly being generated when not required.
+
 ## v2.1.0
 - *Enhancement:* Added `CdcService<TOrchestrator, TEntity>` that provides the base Change Data Capture (CDC) self-orchestrated service capabilities; used for the likes of Azure Functions.
 - *Enhancement:* Added `service: Service` YAML configuration to enable the new  `CdcService<TOrchestrator, TEntity>` code-generation. The `IServiceCollectionExtensions` code-generation also updated to include.

NTangle.sln

@@ -79,9 +79,16 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ContactSync.OldApp.Publishe
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "NewApp", "NewApp", "{6855FFC2-39E7-48D4-AB5D-079D406390FC}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "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}") = "ContactSync.NewApp.Database", "samples\ContactSync\ContactSync.NewApp\ContactSync.NewApp.Database\ContactSync.NewApp.Database.csproj", "{4BADE51C-EA1C-4A68-B591-8F148F5FF975}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ContactSync.NewApp.Subscriber", "samples\ContactSync\ContactSync.NewApp\ContactSync.NewApp.Subscriber\ContactSync.NewApp.Subscriber.csproj", "{D6364CFB-DAAA-41E7-996F-8F1654EECF10}"
+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
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -163,6 +170,7 @@ Global
 		{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}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {B97E5639-3430-4AD7-9942-D35EF26F263B}

samples/ContactSync/ContactSync.OldApp/ContactSync.OldApp.Database/Migrations/Setup.post.database.create.sql

@@ -1,16 +1,4 @@
-/*
- Pre-Deployment Script Template							
---------------------------------------------------------------------------------------
- This file contains SQL statements that will be executed before the build script.	
- Use SQLCMD syntax to include a file in the pre-deployment script.			
- Example:      :r .\myfile.sql								
- Use SQLCMD syntax to reference a variable in the pre-deployment script.		
- Example:      :setvar TableName MyTable							
-               SELECT * FROM [$(TableName)]					
---------------------------------------------------------------------------------------
-*/
-
--- Enable CDC for database
+-- Enable CDC for database
 
 IF (SELECT TOP 1 is_cdc_enabled FROM sys.databases WHERE [name] = DB_NAME()) = 0
 BEGIN

samples/ContactSync/ContactSync.OldApp/ContactSync.OldApp.Publisher/Functions/ContactFunction.cs

@@ -1,12 +1,11 @@
-namespace ContactSync.OldApp.Publisher.Functions
+namespace ContactSync.OldApp.Publisher.Functions;
+
+public class ContactFunction
 {
-    public class ContactFunction
-    {
-        private readonly ContactService _contactService;
+    private readonly ContactService _contactService;
 
-        public ContactFunction(ContactService contactService) => _contactService = contactService.ThrowIfNull();
+    public ContactFunction(ContactService contactService) => _contactService = contactService.ThrowIfNull();
 
-        [FunctionName(nameof(ContactFunction))]
-        public Task RunAsync([TimerTrigger("*/5 * * * * *")] TimerInfo timer, CancellationToken cancellationToken) => _contactService.ExecuteAsync(cancellationToken);
-    }
-}
+    [FunctionName(nameof(ContactFunction))]
+    public Task RunAsync([TimerTrigger("*/5 * * * * *")] TimerInfo timer, CancellationToken cancellationToken) => _contactService.ExecuteAsync(cancellationToken);
+}

samples/ContactSync/ContactSync.OldApp/ContactSync.OldApp.Publisher/Functions/RelayFunction.cs

@@ -0,0 +1,11 @@
+namespace ContactSync.OldApp.Publisher.Functions;
+
+public class RelayFunction
+{
+    private readonly EventOutboxService _eventOutboxService;
+
+    public RelayFunction(EventOutboxService eventOutboxService) => _eventOutboxService = eventOutboxService.ThrowIfNull();
+
+    [FunctionName(nameof(RelayFunction))]
+    public Task RunAsync([TimerTrigger("*/5 * * * * *")] TimerInfo timer, CancellationToken cancellationToken) => _eventOutboxService.ExecuteAsync(cancellationToken);
+}

samples/ContactSync/ContactSync.OldApp/ContactSync.OldApp.Publisher/Startup.cs

@@ -3,7 +3,7 @@
 namespace ContactSync.OldApp.Publisher;
 
 /// <summary>
-/// The console program leveraging <see href="https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host"/>.
+/// The Azure Functions runtime startup leveraging <see href="https://learn.microsoft.com/en-us/azure/azure-functions/functions-dotnet-dependency-injection"/>.
 /// </summary>
 public class Startup : FunctionsStartup
 {

samples/ContactSync/README.md

@@ -52,16 +52,17 @@ This sample will walk through the implementation in a number of logical steps.
 
 ### Old App
 
-1. [_NTangle_]() - solution setup, configuration and code-generation.
-2. [Database]() - apply CDC and schema changes.
-3. [Publish]() - publish events to Azure Service Bus leveraging Azure Functions.
+1. [Setup](./docs/old-app-setup.md) - solution setup, configuration, and database baseline.
+2. [Code-gen](./docs/old-app-code-gen.md) - code-generation and database management. 
+2. [Publish]() - publish events to Azure Service Bus leveraging Azure Functions.
 
 <br/>
 
 ### New App
 
+3. [SetUp]() - solution setup and configuration.
 4. [Database]() - create new database and schema.
-5. [Subscribe]() -  subscribe to events from Azure Service Bus leveraging Azure Function.
+5. [Subscribe]() - subscribe to events from Azure Service Bus leveraging an Azure Function.
 
 <br/>
 

samples/ContactSync/docs/old-app-code-gen.md

@@ -0,0 +1,85 @@
+## Step 2 - Old App Code Generation
+
+This will walk through the configuration and execution of the `OldApp`-related code-generation to output both database and .NET artefacts. 
+
+<br/>
+
+## Code generation
+
+To enable the _NTangle_ capabilities the `ContactSync.OldApp.CodeGen` project must be configured and the corresponding code generation performed to create the requisite database and .NET runtime artefacts.
+
+Similar to the previous `ContactSync.OldApp.Database` project, the connection string within the [`Program.cs`](../ContactSync.OldApp/ContactSync.OldApp.CodeGen/Program.cs) file should be reviewed and amended accordingly.
+
+The specified connection string is intended as the default for development only. This value can also be specified at runtime via the command line arguments. To see the available command line arguments etc. issue the following command from the `ContactSync.OldApp.CodeGen` folder.
+
+```
+dotnet run -- --help
+```
+
+<br/>
+
+### Configuration
+
+The `ntangle.yaml` must be configured to enable the code generation. Replace the existing contents with the following. 
+
+In summary, the configuration defines both the `contact` and `contact_address` tables as being CDC-triggered and are renamed. The relationship between them is defined including the corresponding cardinality of one-to-one. Their corresponding columns have been renamed using an alias to produce the desired .NET naming convention. The global settings are also defined within the YAML. All possible YAML configuration settings are documented [here](../../../docs/generated/root.md).
+
+```yaml
+schema: old                                          # Defaults the schema for the non-CDC related tables.
+cdcSchema: NTangle                                   # Defines the name of the schema to be used for CDC-related artefacts.
+cdcSchemaCreate: true                                # Indicates whether to create the CDC database schema via code-generation.
+cdcEnable: true                                      # Indicates whether to enable CDC for the referenced table(s) in the database (recommend managing explicitly).
+eventSourceRoot: /database/old/cdc                   # Event source URI root prepended to all published events.
+eventSubjectRoot: old                                # Event subject root prepended to all published events.
+outbox: true                                         # Indicates to include the generation of the event outbox artefacts.
+outboxSchemaCreate: true                             # Indicates whether to create the Outbox database schema via code-generation.
+service: Service                                     # Create the entity-based "Service" type to be executed by the likes of an Azure Function.
+tables:
+  # Set up CDC-entity for primary table old.contact; note rename of table and columns.
+- { name: Contact, table: contact, eventSubject: Contact, aliasColumns: [ contact_id^Id, contact_name^Name, contact_phone^Phone, contact_email^Email, contact_active^IsActive, contact_no_calling^NoCallList ], excludeColumns: [ contact_addressid ],
+    joins: [
+      # Set up secondary CDC-triggered One-To-One relationship (join) from old.contact to old.contact_address renaming the table and columns.
+      { name: Address, table: contact_address, joinCardinality: OneToOne, excludeColumns: [ contact_address_id ], aliasColumns: [ contact_address_id^Id, address_street_1^Street1, address_street_2^Street2 ],
+        on: [
+          { name: contact_address_id, toColumn: contact_addressid }
+        ]
+      }
+    ]
+  }
+```
+
+<br/>
+
+### Execute code generation
+
+Once the configuration has been completed then the code-generation is performed. Remember that the code-generation is _gen-many_ meaning that at any time the code-generation can be re-executed to create/update the related artefacts; such as schema changes to related tables, or the addition of new tables, etc.
+
+Issue the following command from the `ContactSync.OldApp.CodeGen` folder to execute the code-generation.
+
+```
+dotnet run
+```
+
+<br/>
+
+## Database management
+
+Return to the `ContactSync.OldApp.Database` project. Within the `Migrations` and `Schema` folders new artefacts will have been created as a result of the preceeding code-generation. These include the _NTangle_ and _Outbox_ related tables and stored procedures. 
+
+Using the inherited _DbEx_ capabilities, the database can be updated to include these new artefacts. Issue the following command from the `ContactSync.OldApp.Database` folder.
+
+```
+dotnet run database
+```
+
+_Note:_ It is recommended that the `CdcEnable.post.deploy.sql` be reviewed as this is intended for demo purposes only; this should not be used for production/actual use, and that the equivalent script(s) are managed manually to get the appropriate/desired outcome. To turn off the code-generation for this, update the YAML setting to `cdcEnable: false` or remove the configuration altogether.
+
+Finally, the database mamagement capabilities can be leveraged (where applicable) to manage the database changes in the various environments; for example, development, testing and production.
+
+<br/>
+
+## Conclusion
+
+At this stage we have now executed the _NTangle_ code-generation against the `OldApp` database, and output both the database and .NET artefacts. The database has been updated to include the _NTangle_ and _Outbox_ related tables and stored procedures, etc.
+
+Next we will update the _NTangle_ [publisher](./old-app-publish.md) project as the deployed component that leverages CDC to execute the event publish triggering.