Merge pull request #524 from Kentico/feat/media-folder-restrictions

Check XbyK media folder restrictions

Author: fialafilip

KVA/Migration.Tool.Source/Services/MediaFileMigrator.cs

@@ -186,11 +186,7 @@ private void RequireMigratedMediaFiles(List<(IMediaLibrary sourceLibrary, ICmsSi
 
                     try
                     {
-                        if (newInstance)
-                        {
-                            mediaFileFacade.EnsureMediaFilePathExistsInLibrary(mf, targetMediaLibrary.LibraryID);
-                        }
-
+                        mediaFileFacade.EnsureMediaFilePathExistsInLibrary(mf, targetMediaLibrary.LibraryID);
                         mediaFileFacade.SetMediaFile(mf, newInstance);
 
                         protocol.Success(ksMediaFile, mf, mapped);

Migration.Tool.CLI/README.md

@@ -430,6 +430,7 @@ Add the options under the `Settings` section in the configuration file.
 | MigrateOnlyMediaFileInfo                                          | If set to `true`, only the database representations of media files are migrated, without the files in the media folder in the project's file system. For example, enable this option if your media library files are mapped to a shared directory or Cloud storage.<br /><br />If `false`, media files are migrated based on the `KxCmsDirPath` location.                                                                                                                                                                                                  |
 | MigrateMediaToMediaLibrary                                        | Determines whether media library files and attachments from the source instance are migrated to the target instance as media libraries or as [content item assets](https://docs.kentico.com/x/content_item_assets_xp) in the content hub. The default value is `false` – media files and attachments are migrated as content item assets. <br /><br /> See [Convert attachments and media library files to media libraries instead of content item assets](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) |
 | LegacyFlatAssetTree                                               | Use legacy behavior of versions up to 2.3.0. Content folders for asset content items will be created in a flat structure (all under root folder)                                                                                                                                                                                                                                                                                                                                                                                                           |
+| LegacyPermissiveMediaLibrarySubfolders                            | XbyK has restrictions on media library subfolder name. It must contain only alphanumeric characters, underscores ('_'), hyphens ('-'), and cannot contain file names reserved by the operating system (e.g., ‘CON’, ‘PRN’, ‘AUX’ for Windows). If set to `true`, name checks will be bypassed. Note that this may impair some XbyK functionality like migration of media libraries to content hub. User may prefer using this option e.g. for repeated migration after initially migrating with previous versions of Migration Tool, and then manually changing the names in XbyK |                                                                                                                                                                                                                                                                                                                                                                                                             |
 | AssetRootFolders                                                  | Dictionary defining the root folder for Asset content items per site: Key is site name (CMS_Site.SiteName). Value is in format _/FolderDisplayName1/FolderDisplayName2/..._                                                                                                                                                                                                                                                                                                                                                                                |
 | TargetWorkspaceName                                               | The code name of the [workspace](https://docs.kentico.com/x/workspaces_xp) to which content items, content folders and other related entities are migrated. This workspace is used if another workspace is not specified explicitly, for example by the content item director API in [migration customizations](../Migration.Tool.Extensions/README.md). This configuration is not necessary if the target project only contains a single workspace.                                                                                                                                                         |
 | MemberIncludeUserSystemFields                                     | Determines which system fields from the _CMS_User_ and _CMS_UserSettings_ tables are migrated to _CMS_Member_ in Xperience by Kentico. Fields that do not exist in _CMS_Member_ are automatically created. <br /><br />The sample `appsettings.json` file included with the tool by default includes all user fields that can be migrated from Kentico Xperience 13. Exclude specific fields from the migration by removing them from this configuration option.                                                                                           |

Migration.Tool.CLI/appsettings.json

@@ -28,6 +28,7 @@
     "MigrateOnlyMediaFileInfo": false,
     "MigrateMediaToMediaLibrary": false,
     "LegacyFlatAssetTree": false,
+    "LegacyPermissiveMediaLibrarySubfolders": false,
     "AssetRootFolders": {},
     "UseDeprecatedFolderPageType": false,
     "ConvertClassesToContentHub": "",

Migration.Tool.Common/ConfigurationNames.cs

@@ -24,6 +24,7 @@ public class ConfigurationNames
 
     public const string MigrateMediaToMediaLibrary = "MigrateMediaToMediaLibrary";
     public const string LegacyFlatAssetTree = "LegacyFlatAssetTree";
+    public const string LegacyPermissiveMediaLibrarySubfolders = "LegacyPermissiveMediaLibrarySubfolders";
     public const string AssetRootFolders = "AssetRootFolders";
 
     public const string UseDeprecatedFolderPageType = "UseDeprecatedFolderPageType";

Migration.Tool.Common/ToolConfiguration.cs

@@ -49,6 +49,9 @@ public class ToolConfiguration
     [ConfigurationKeyName(ConfigurationNames.LegacyFlatAssetTree)]
     public bool? LegacyFlatAssetTree { get; set; }
 
+    [ConfigurationKeyName(ConfigurationNames.LegacyPermissiveMediaLibrarySubfolders)]
+    public bool? LegacyPermissiveMediaLibrarySubfolders { get; set; }
+
     [ConfigurationKeyName(ConfigurationNames.AssetRootFolders)]
     public Dictionary<string, string>? AssetRootFolders { get; set; }
 

Migration.Tool.KXP.Api/KxpMediaFileFacade.cs

@@ -1,17 +1,22 @@
 using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Text.RegularExpressions;
 using CMS.DataEngine;
 using CMS.MediaLibrary;
 using Microsoft.Extensions.Logging;
+using Migration.Tool.Common;
 
 namespace Migration.Tool.KXP.Api;
 
 public class KxpMediaFileFacade
 {
     private readonly ILogger<KxpMediaFileFacade> logger;
+    private readonly ToolConfiguration toolConfiguration;
 
-    public KxpMediaFileFacade(ILogger<KxpMediaFileFacade> logger, KxpApiInitializer kxpApiInitializer)
+    public KxpMediaFileFacade(ILogger<KxpMediaFileFacade> logger, KxpApiInitializer kxpApiInitializer, ToolConfiguration toolConfiguration)
     {
         this.logger = logger;
+        this.toolConfiguration = toolConfiguration;
         kxpApiInitializer.EnsureApiIsInitialized();
     }
 
@@ -42,11 +47,72 @@ public void SetMediaFile(MediaFileInfo mfi, bool newInstance)
     public MediaLibraryInfo GetMediaLibraryInfo(Guid mediaLibraryGuid) => MediaLibraryInfoProvider.ProviderObject.Get(mediaLibraryGuid);
 #pragma warning restore CS0618 // Type or member is obsolete
 
+    public static bool IsDirectoryNameAllowed(string name)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+        {
+            return false;
+        }
+
+        if (!name.All(x => char.IsLetterOrDigit(x) || new char[] { '-', '_', System.IO.Path.DirectorySeparatorChar, System.IO.Path.AltDirectorySeparatorChar }.Contains(x)))
+        {
+            return false;
+        }
+
+        // Reserved device names (Windows only)
+        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            string[] reserved = {
+                "CON", "PRN", "AUX", "NUL",
+                "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+                "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"
+            };
+
+            string upper = name.ToUpperInvariant();
+            if (reserved.Contains(upper) || reserved.Any(r => upper.StartsWith(r + ".", StringComparison.Ordinal)))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private readonly HashSet<string> fixedFolderPaths = [];
+
 #pragma warning disable CS0618 // Type or member is obsolete
     public void EnsureMediaFilePathExistsInLibrary(MediaFileInfo mfi, int libraryId)
 #pragma warning restore CS0618 // Type or member is obsolete
     {
         string? librarySubDir = System.IO.Path.GetDirectoryName(mfi.FilePath);
+        if (toolConfiguration.LegacyFlatAssetTree != true)
+        {
+            if (!string.IsNullOrEmpty(librarySubDir) && !IsDirectoryNameAllowed(librarySubDir))
+            {
+                // Try an automatic correction - replacing stretches of whitespaces with underscore.
+                // If that succeeds, inform user by a warning. Otherwise raise error and defer fixing the issue to user.
+                string fixedLibrarySubdir = Regex.Replace(librarySubDir.Trim(), @"\s+", "-");
+
+                string bypassMessage = $"If you want to bypass this, use {nameof(toolConfiguration.LegacyPermissiveMediaLibrarySubfolders)} appsettings option. Please refer to README for potential sideeffects.";
+
+                if (IsDirectoryNameAllowed(fixedLibrarySubdir))
+                {
+                    librarySubDir = fixedLibrarySubdir;
+                    mfi.FilePath = $"{librarySubDir}/{System.IO.Path.GetFileName(mfi.FilePath)}";   // Don't use Path.Combine, because it doesn't work correctly with subsequent internal CMS logic
+
+                    if (!fixedFolderPaths.Contains(librarySubDir))
+                    {
+                        fixedFolderPaths.Add(librarySubDir);
+                        logger.LogWarning($"Media library subfolder '{{MediaLibrarySubfolder}}' was transformed to XbyK allowed format '{{FixedMediaLibrarySubfolder}}'. {bypassMessage}", librarySubDir, fixedLibrarySubdir);
+                    }
+                }
+                else
+                {
+                    throw new InvalidOperationException($"Media library subfolder name {librarySubDir} is not in XbyK allowed format. It must contain only alphanumeric characters, underscores ('_'), hyphens ('-'), and cannot contain file names reserved by the operating system. {bypassMessage}");
+                }
+            }
+        }
+
 #pragma warning disable CS0618 // Type or member is obsolete
         MediaLibraryInfoProvider.CreateMediaLibraryFolder(libraryId, $"{librarySubDir}");
 #pragma warning restore CS0618 // Type or member is obsolete