Merge pull request #42 from tableau/release/5.0.0

Release 5.0.0
tableau · Oct 30, 2024 · 43205e9 · 43205e9
2 parents 587b9dc + 9460621
commit 43205e9
Show file tree

Hide file tree

Showing 158 changed files with 5,150 additions and 1,444 deletions.
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -4,7 +4,7 @@
 		<Nullable>enable</Nullable>
 		<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
 		<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
-		<Version>4.3.1</Version>
+		<Version>5.0.0</Version>
 		<Authors>Salesforce, Inc.</Authors>
 		<Company>Salesforce, Inc.</Company>
 		<Copyright>Copyright (c) 2024, Salesforce, Inc. and its licensors</Copyright>

diff --git a/examples/Csharp.ExampleApplication/Csharp.ExampleApplication.csproj b/examples/Csharp.ExampleApplication/Csharp.ExampleApplication.csproj
@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 	<PropertyGroup>
 		<OutputType>Exe</OutputType>
-		<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
+		<TargetFrameworks>net8.0</TargetFrameworks>
 		<!-- Don't warn on ConfigureAwait on console application, Don't require license headers for sample code -->
 		<NoWarn>CA2007,IDE0073</NoWarn>
 		<UserSecretsId>8368baab-103b-45f6-bfb1-f89a537f4f3c</UserSecretsId>
@@ -10,7 +10,7 @@
 		<ProjectReference Include="../../src/Tableau.Migration/Tableau.Migration.csproj" />		
 	</ItemGroup>
 	<ItemGroup>
-		<PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
+		<PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.1" />
 	</ItemGroup>
 	<ItemGroup>
 	  <None Update="appsettings.Development.json">

diff --git a/examples/Csharp.ExampleApplication/Hooks/InitializeMigration/CustomContext.cs b/examples/Csharp.ExampleApplication/Hooks/InitializeMigration/CustomContext.cs
@@ -0,0 +1,13 @@
+using System;
+
+namespace Csharp.ExampleApplication.Hooks.InitializeMigration
+{
+    #region class
+
+    public class CustomContext
+    {
+        public Guid CustomerId { get; set; }
+    }
+
+    #endregion
+}
diff --git a/examples/Csharp.ExampleApplication/Hooks/InitializeMigration/SetMigrationContextHook.cs b/examples/Csharp.ExampleApplication/Hooks/InitializeMigration/SetMigrationContextHook.cs
@@ -0,0 +1,23 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.DependencyInjection;
+using Tableau.Migration.Engine.Hooks;
+
+namespace Csharp.ExampleApplication.Hooks.InitializeMigration
+{
+    #region class
+
+    internal class SetMigrationContextHook : IInitializeMigrationHook
+    {
+        public Task<IInitializeMigrationHookResult?> ExecuteAsync(IInitializeMigrationHookResult ctx, CancellationToken cancel)
+        {
+            var customContext = ctx.ScopedServices.GetRequiredService<CustomContext>();
+            customContext.CustomerId = Guid.NewGuid();
+
+            return Task.FromResult<IInitializeMigrationHookResult?>(ctx);
+        }
+    }
+
+    #endregion
+}
diff --git a/examples/Csharp.ExampleApplication/MyMigrationApplication.cs b/examples/Csharp.ExampleApplication/MyMigrationApplication.cs
@@ -8,6 +8,7 @@
 using Csharp.ExampleApplication.Config;
 using Csharp.ExampleApplication.Hooks.BatchMigrationCompleted;
 using Csharp.ExampleApplication.Hooks.Filters;
+using Csharp.ExampleApplication.Hooks.InitializeMigration;
 using Csharp.ExampleApplication.Hooks.Mappings;
 using Csharp.ExampleApplication.Hooks.MigrationActionCompleted;
 using Csharp.ExampleApplication.Hooks.PostPublish;
@@ -147,6 +148,11 @@ public async Task StartAsync(CancellationToken cancel)
             _planBuilder.Transformers.Add<CustomViewExcludeDefaultUserTransformer, IPublishableCustomView>();
             #endregion
 
+            // Add initialize migration hooks
+            #region SetCustomContext-Registration
+            _planBuilder.Hooks.Add<SetMigrationContextHook>();
+            #endregion
+
             // Add migration action completed hooks
             #region LogMigrationActionsHook-Registration
             _planBuilder.Hooks.Add<LogMigrationActionsHook>();

diff --git a/examples/Csharp.ExampleApplication/Program.cs b/examples/Csharp.ExampleApplication/Program.cs
@@ -2,6 +2,7 @@
 using Csharp.ExampleApplication.Config;
 using Csharp.ExampleApplication.Hooks.BatchMigrationCompleted;
 using Csharp.ExampleApplication.Hooks.Filters;
+using Csharp.ExampleApplication.Hooks.InitializeMigration;
 using Csharp.ExampleApplication.Hooks.Mappings;
 using Csharp.ExampleApplication.Hooks.MigrationActionCompleted;
 using Csharp.ExampleApplication.Hooks.PostPublish;
@@ -44,6 +45,14 @@ public static async Task Main(string[] args)
         /// <returns>The same service collection as the <paramref name="services"/> parameter.</returns>
         public static IServiceCollection AddCustomizations(this IServiceCollection services)
         {
+            #region SetCustomContext-Service-DI
+            services.AddScoped<CustomContext>();
+            #endregion
+
+            #region SetCustomContext-Hook-DI
+            services.AddScoped<SetMigrationContextHook>();
+            #endregion
+
             #region EmailDomainMapping-DI
             services.AddScoped<EmailDomainMapping>();
             #endregion

diff --git a/...ples/DependencyInjection.ExampleApplication/DependencyInjection.ExampleApplication.csproj b/...ples/DependencyInjection.ExampleApplication/DependencyInjection.ExampleApplication.csproj
@@ -2,13 +2,13 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-		<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
+		<TargetFrameworks>net8.0</TargetFrameworks>
 		<!-- Don't warn on ConfigureAwait on console application, Don't require license headers for sample code -->
 	  <NoWarn>CA2007,IDE0073</NoWarn>
 	</PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.1" />
   </ItemGroup>
 
   <ItemGroup>

diff --git a/examples/Python.ExampleApplication/Hooks/initialize_migration/set_custom_context_hook.py b/examples/Python.ExampleApplication/Hooks/initialize_migration/set_custom_context_hook.py
@@ -0,0 +1,10 @@
+from tableau_migration import(
+    InitializeMigrationHookBase,
+    IInitailizeMigrationHookResult
+)
+
+from Csharp.ExampleApplication.Hooks.InitializeMigration import CustomContext
+
+class SetMigrationContextHook(InitializeMigrationHookBase):
+    def execute(self, ctx: IInitailizeMigrationHookResult) -> IInitailizeMigrationHookResult:
+        ctx.scoped_services._get_service(CustomContext)
diff --git a/examples/Python.ExampleApplication/Python.ExampleApplication.pyproj b/examples/Python.ExampleApplication/Python.ExampleApplication.pyproj
@@ -25,6 +25,7 @@
     <Compile Include="hooks\batch_migration_completed\log_migration_batches_hook.py" />
     <Compile Include="hooks\filters\default_project_filter.py" />
     <Compile Include="hooks\filters\unlicensed_user_filter.py" />
+    <Compile Include="hooks\initialize_migration\set_custom_context_hook.py" />
     <Compile Include="hooks\mappings\change_project_mapping.py" />
     <Compile Include="hooks\mappings\email_domain_mapping.py" />
     <Compile Include="hooks\mappings\project_rename_mapping.py" />
@@ -60,6 +61,7 @@
     <Folder Include="hooks\mappings\" />
     <Folder Include="hooks\migration_action_completed\" />
     <Folder Include="hooks\batch_migration_completed\" />
+    <Folder Include="hooks\initialize_migration\" />
     <Folder Include="hooks\post_publish\" />
     <Folder Include="hooks\transformers\" />
   </ItemGroup>

diff --git a/examples/Python.ExampleApplication/print_result.py b/examples/Python.ExampleApplication/print_result.py
@@ -1,15 +1,18 @@
-from tableau_migration.migration import PyMigrationResult
-from tableau_migration import IMigrationManifestEntry, MigrationManifestEntryStatus
-from Tableau.Migration.Engine.Pipelines import ServerToCloudMigrationPipeline
+from tableau_migration import (
+    IMigrationManifestEntry, 
+    MigrationManifestEntryStatus, 
+    MigrationResult,
+    ServerToCloudMigrationPipeline
+)
 
-def print_result(result: PyMigrationResult):
+def print_result(result: MigrationResult):
         """Prints the result of a migration."""
         print(f'Result: {result.status}')
 
-        for pipeline_content_type in ServerToCloudMigrationPipeline.ContentTypes:
-            content_type = pipeline_content_type.ContentType
+        for pipeline_content_type in ServerToCloudMigrationPipeline.content_types():
+            content_type = pipeline_content_type.content_type
 
-            type_entries = [IMigrationManifestEntry(x) for x in result.manifest.entries.ForContentType(content_type)]
+            type_entries = [IMigrationManifestEntry(x) for x in result.manifest.entries.for_content_type(content_type)]
 
             count_total = len(type_entries)
 

diff --git a/global.json b/global.json
@@ -1,6 +1,6 @@
 {
   "sdk": {
-    "version": "8.0.302",
+    "version": "8.0.403",
     "rollForward": "latestMajor"
   }
 }
diff --git a/src/Documentation/articles/hooks/custom_hooks.md b/src/Documentation/articles/hooks/custom_hooks.md
@@ -11,15 +11,16 @@ Here are some important things to know when writing custom hooks:
 ## [Python](#tab/Python)
 
 The base classes can be used as they are linked in the API reference. However, for ease of use, all base classes have been imported into the `tableau_migration` namespace without the `Py` prefix.
-For example: [`PyContentFilterBase`](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.PyContentFilterBase.md) has been imported as `tableau_migration.PyContentFilterBase`.
+For example: [`PyContentFilterBase`](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.PyContentFilterBase.md) has been imported as `tableau_migration.ContentFilterBase`.
 
 #### Pre-Migration
 
-| Type                                                                                                    | Base Class                                                                                                                                             | Code Samples                                                 |
-|---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
-| [Filters](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.md)           | [`ContentFilterBase<TContent>`](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.PyContentFilterBase.md)                | [Code Samples/Filters](~/samples/filters/index.md)           |
-| [Mappings](~/api-python/reference/tableau_migration.migration_engine_hooks_mappings_interop.md)         | [`ContentMappingBase<TContent>`](~/api-python/reference/tableau_migration.migration_engine_hooks_mappings_interop.PyContentMappingBase.md)             | [Code Samples/Mappings](~/samples/mappings/index.md)         |
-| [Transformers](~/api-python/reference/tableau_migration.migration_engine_hooks_transformers_interop.md) | [`ContentTransformerBase<TPublish>`](~/api-python/reference/tableau_migration.migration_engine_hooks_transformers_interop.PyContentTransformerBase.md) | [Code Samples/Transformers](~/samples/transformers/index.md) |
+| Type                                                                                                    | Base Class                                                                                                                                             | Code Samples                                                                 |
+|---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
+| [Initialize Migration](~/api-python/reference/tableau_migration.migration_engine_hooks_interop.md)      | [`InitializeMigrationHookBase`](~/api-python/reference/tableau_migration.migration_engine_hooks_interop.PyInitializeMigrationHookBase.md)              | [Code Samples/Initialize Migration](~/samples/initialize-migration/index.md) |
+| [Filters](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.md)           | [`ContentFilterBase<TContent>`](~/api-python/reference/tableau_migration.migration_engine_hooks_filters_interop.PyContentFilterBase.md)                | [Code Samples/Filters](~/samples/filters/index.md)                           |
+| [Mappings](~/api-python/reference/tableau_migration.migration_engine_hooks_mappings_interop.md)         | [`ContentMappingBase<TContent>`](~/api-python/reference/tableau_migration.migration_engine_hooks_mappings_interop.PyContentMappingBase.md)             | [Code Samples/Mappings](~/samples/mappings/index.md)                         |
+| [Transformers](~/api-python/reference/tableau_migration.migration_engine_hooks_transformers_interop.md) | [`ContentTransformerBase<TPublish>`](~/api-python/reference/tableau_migration.migration_engine_hooks_transformers_interop.PyContentTransformerBase.md) | [Code Samples/Transformers](~/samples/transformers/index.md)                 |
 
 #### Post-Migration
 
@@ -38,11 +39,12 @@ To register Python hooks, register the object with the appropriate hook type lis
 
 #### Pre-Migration
 
-| Type											                                                          | Base Class		                                                                                                                                   | Interface 		                                                                                           | Code Samples		                                          |
-|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
-| [Filters](xref:Tableau.Migration.Engine.Hooks.Filters)                                                  | [`ContentFilterBase<TContent>`](xref:Tableau.Migration.Engine.Hooks.Filters.ContentFilterBase`1)                                                   | [`IContentFilter<TContent>`](xref:Tableau.Migration.Engine.Hooks.Filters.IContentFilter`1)                | [Code Samples/Filters](~/samples/filters/index.md)           |
-| [Mappings](xref:Tableau.Migration.Engine.Hooks.Mappings)                                                | [`ContentMappingBase<TContent>`](xref:Tableau.Migration.Engine.Hooks.Mappings.ContentMappingBase`1)                                                | [`IContentMapping<TContent>`](xref:Tableau.Migration.Engine.Hooks.Mappings.IContentMapping`1)             | [Code Samples/Mappings](~/samples/mappings/index.md)         |
-| [Transformers](xref:Tableau.Migration.Engine.Hooks.Transformers)                                        | [`ContentTransformerBase<TPublish>`](xref:Tableau.Migration.Engine.Hooks.Transformers.ContentTransformerBase`1)                                    | [`IContentTransformer<TPublish>`](xref:Tableau.Migration.Engine.Hooks.Transformers.IContentTransformer`1) | [Code Samples/Transformers](~/samples/transformers/index.md) |
+| Type											                                                          | Base Class		                                                                                                                                   | Interface 		                                                                                           | Code Samples		                                                          |
+|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
+| [Initialize Migration](xref:Tableau.Migration.Engine.Hooks)                                             | None                                                                                                                                               | [`IInitializeMigrationHook`](xref:Tableau.Migration.Engine.Hooks.IInitializeMigrationHook)                | [Code Samples/Initialize Migration](~/samples/initialize-migration/index.md) |
+| [Filters](xref:Tableau.Migration.Engine.Hooks.Filters)                                                  | [`ContentFilterBase<TContent>`](xref:Tableau.Migration.Engine.Hooks.Filters.ContentFilterBase`1)                                                   | [`IContentFilter<TContent>`](xref:Tableau.Migration.Engine.Hooks.Filters.IContentFilter`1)                | [Code Samples/Filters](~/samples/filters/index.md)                           |
+| [Mappings](xref:Tableau.Migration.Engine.Hooks.Mappings)                                                | [`ContentMappingBase<TContent>`](xref:Tableau.Migration.Engine.Hooks.Mappings.ContentMappingBase`1)                                                | [`IContentMapping<TContent>`](xref:Tableau.Migration.Engine.Hooks.Mappings.IContentMapping`1)             | [Code Samples/Mappings](~/samples/mappings/index.md)                         |
+| [Transformers](xref:Tableau.Migration.Engine.Hooks.Transformers)                                        | [`ContentTransformerBase<TPublish>`](xref:Tableau.Migration.Engine.Hooks.Transformers.ContentTransformerBase`1)                                    | [`IContentTransformer<TPublish>`](xref:Tableau.Migration.Engine.Hooks.Transformers.IContentTransformer`1) | [Code Samples/Transformers](~/samples/transformers/index.md)                 |
 
 #### Post-Migration
 

diff --git a/src/Documentation/articles/hooks/index.md b/src/Documentation/articles/hooks/index.md
@@ -35,13 +35,15 @@ These types of hooks run on content items.
 
 These types of hooks run before or after certain migration events.
 
+- Migration Initialized: Executed after preflight validation is completed successfully, but before any migration actions are started.
+
 - Post-Publish: Run on the destination content after the items for the content type have been published.
 
-- Bulk Post-Publish: Execute after publishing a batch of content, when bulk publishing is supported. You can make changes to the published set of items with this type of hook. You can write this type of hook for content types such as Users.
+- Bulk Post-Publish: Executed after publishing a batch of content, when bulk publishing is supported. You can make changes to the published set of items with this type of hook. You can write this type of hook for content types such as Users.
 
-- Migration Action Completed: Execute after the migration of each content type.
+- Migration Action Completed: Executed after the migration of each content type.
 
-- Batch Migration Completed: Execute after the completion of the migration of a batch of Tableau’s content.
+- Batch Migration Completed: Executed after the completion of the migration of a batch of Tableau’s content.
 
 ## Hook execution flow
 

diff --git a/src/Documentation/samples/initialize-migration/index.md b/src/Documentation/samples/initialize-migration/index.md
@@ -0,0 +1,7 @@
+# Initialize Migration
+
+Initialize Migration Hooks allow custom logic to run after a migration startup has been validated but before any migration work is performed.
+
+The following samples cover some common scenarios:
+
+- [Sample: Set Custom Migration Scoped Context](~/samples/initialize-migration/set_custom_context.md)
diff --git a/src/Documentation/samples/initialize-migration/set_custom_context.md b/src/Documentation/samples/initialize-migration/set_custom_context.md
@@ -0,0 +1,57 @@
+# Sample: Set Custom Migration Scoped Context
+
+This example demonstrates how to set custom context in the migration scoped dependency injection container using an initialize migration hook.
+This is useful when other hooks like filters are registered with dependency injection and rely on migration scoped services.
+
+# [Python](#tab/Python)
+
+#### Custom Context Service Class
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Hooks/InitializeMigration/CustomContext.cs#class)]
+
+#### Custom Context Service Class Dependency Injection
+
+[Learn more.](~/articles/dependency_injection.md)
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Program.cs#SetCustomContext-Service-DI)]
+
+#### Initialize Migration Hook Class
+
+[!code-python[](../../../../examples/Python.ExampleApplication/hooks/initialize_migration/set_custom_context_hook.py)]
+
+#### Registration
+
+[Learn more.](~/samples/index.md?tabs=Python#hook-registration)
+
+[//]: <> (Adding this as code as regions are not supported in Python snippets)
+```Python
+plan_builder.hooks.add(SetMigrationContextHook)
+```
+
+# [C#](#tab/CSharp)
+
+#### Custom Context Service Class
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Hooks/InitializeMigration/CustomContext.cs#class)]
+
+#### Custom Context Service Class Dependency Injection
+
+[Learn more.](~/articles/dependency_injection.md)
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Program.cs#SetCustomContext-Service-DI)]
+
+#### Initialize Migration Hook Class
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Hooks/InitializeMigration/SetMigrationContextHook.cs#class)]
+
+#### Registration
+
+[Learn more.](~/samples/index.md?tabs=CSharp#hook-registration)
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/MyMigrationApplication.cs#SetCustomContext-Registration)]
+
+#### Dependency Injection
+
+[Learn more.](~/articles/dependency_injection.md)
+
+[!code-csharp[](../../../../examples/Csharp.ExampleApplication/Program.cs#SetCustomContext-Hook-DI)]