extensibility docs

Migration.Tool.Extensions/README.md

@@ -0,0 +1,17 @@
+## Custom migrations
+
+Samples:
+- `Migration.Tool.Extensions/CommunityMigrations/SampleTextMigration.cs` contains simplest implementation for migration of text fields
+- `Migration.Tool.Extensions/DefaultMigrations/AssetMigration.cs` contains real world migration of assets (complex example)
+
+To create custom migration:
+- create new file in `Migration.Tool.Extensions/CommunityMigrations` (directory if you need more files for single migration)
+- implement interface `Migration.Toolkit.KXP.Api.Services.CmsClass.IFieldMigration`
+  - implement property rank, set number bellow 100 000 - for example 5000
+  - implement method shall migrate (if method returns true, migration will be used)
+  - implement `MigrateFieldDefinition`, where objective is to mutate argument `XElement field` that represents one particular field
+  - implement `MigrateValue` where goal is to return new migrated value derived from `object? sourceValue`
+- finally register in `Migration.Tool.Extensions/ServiceCollectionExtensions.cs` as `Transient` dependency into service collection. For example `services.AddTransient<IFieldMigration, AssetMigration>()`
+
+## Custom re-modeling of page types
+

Migration.Tool.Extensions/ServiceCollectionExtensions.cs

@@ -1,4 +1,5 @@
 using Microsoft.Extensions.DependencyInjection;
+using Migration.Tool.Extensions.ClassMappings;
 using Migration.Tool.Extensions.CommunityMigrations;
 using Migration.Tool.Extensions.DefaultMigrations;
 using Migration.Toolkit.KXP.Api.Services.CmsClass;
@@ -12,9 +13,9 @@ public static IServiceCollection UseCustomizations(this IServiceCollection servi
         services.AddTransient<IFieldMigration, AssetMigration>();
         services.AddTransient<IFieldMigration, SampleTextMigration>();
 
-        // services.AddClassMergeExample();
-        // services.AddSimpleRemodelingSample();
-        // services.AddReusableSchemaIntegrationSample();
+        services.AddClassMergeExample();
+        services.AddSimpleRemodelingSample();
+        services.AddReusableSchemaIntegrationSample();
         return services;
     }
 }

Migration.Toolkit.KXP.Api/Services/CmsClass/FormFieldMappingModel.cs

@@ -25,10 +25,32 @@ public record FieldMigrationContext(string SourceDataType, string? SourceFormCon
 public record FieldMigrationResult(bool Success, object? MigratedValue);
 public interface IFieldMigration
 {
+    /// <summary>
+    /// custom migrations are sorted by this number, first encountered migration wins. Values higher than 100 000 are set to default migrations, set number bellow 100 000 for custom migrations
+    /// </summary>
     int Rank { get; }
+
+    /// <summary>
+    /// Methods determines if this migration is usable in context 
+    /// </summary>
+    /// <param name="context">Expect multiple context types: <see cref="Migration.Toolkit.KXP.Api.Services.CmsClass.FieldMigrationContext"/> for pages, <see cref="Migration.Toolkit.KXP.Api.Services.CmsClass.EmptySourceObjectContext"/> for data class</param>
+    /// <returns></returns>
     bool ShallMigrate(FieldMigrationContext context);
 
+    /// <summary>
+    /// Performs migration of FormField, result is mutated property field
+    /// </summary>
+    /// <param name="formDefinitionPatcher">Helper class for execution of common functionalities</param>
+    /// <param name="field">Field for migration</param>
+    /// <param name="columnTypeAttr">field type - in xml "columntype"</param>
+    /// <param name="fieldDescriptor">field name or field GUID if field name is not specified</param>
     void MigrateFieldDefinition(FormDefinitionPatcher formDefinitionPatcher, XElement field, XAttribute? columnTypeAttr, string fieldDescriptor);
+    /// <summary>
+    /// Performs migration of field value
+    /// </summary>
+    /// <param name="sourceValue">Value from source instance for migration directly from database reader (DBNull may be encountered)</param>
+    /// <param name="context">Context <see cref="Migration.Toolkit.KXP.Api.Services.CmsClass.FieldMigrationContext"/> for pages</param>
+    /// <returns>If migration of field succeeds, returns success and migrated value. If not, returns false as success and null reference as value</returns>
     Task<FieldMigrationResult> MigrateValue(object? sourceValue, FieldMigrationContext context);
 }