[CI Environment] Implemented name shortening for TemplateSpecs artifacts & extended docs (#2589)

* Update to latest

* Updated docs

Author: AlexanderSehr

docs/wiki/The CI environment - Publishing.md

@@ -1,6 +1,7 @@
 This section provides an overview of the principles the publishing is built upon, how it is set up, and how you can interact with it.
 
 - [Publishing overview](#publishing-overview)
+- [Module identifiers](#module-identifiers)
 - [How it works](#how-it-works)
   - [Example scenario](#example-scenario)
   - [Output example](#output-example)
@@ -17,11 +18,79 @@ The publishing phase concludes each module's pipeline. If all previous tests suc
 
 Besides the publishing phase's runtime, there is also the possibility to set the switch `Publish prerelease module`. This switch makes it possible to publish a prerelease version in every workflow run that is not based on `main` or `master`. This can be controlled when running the module pipeline leveraging [Module pipeline inputs](./The%20CI%20environment%20-%20Pipeline%20design#module-pipeline-inputs).
 
-> **Note**<br>
-> The `version` used for publishing any artifact is the same for all three target locations, which reduces the maintenance effort.
+> **Note**: The `version` used for publishing any artifact is the same for all three target locations, which reduces the maintenance effort.
 
 > **Note:** The orchestration options described in the [solution creation](./Solution%20creation) section work differently well with the publishing locations we offer in CARML. To help you select the best location for your use case, we provide further information [here](./Solution%20creation#publish-location-considerations) section.
 
+## Module identifiers
+
+The names of published modules differ slighly depending on the location they are published to. This is rooted in the different requirements per target location. In the following you can find the rules applied for each:
+
+<details>
+<summary>Template Specs</summary>
+
+**Actions**
+
+- Remove the root folder name `modules` from provided module reference
+- Make lowercase
+- Replace `Microsoft` with `MS`
+- Replace all `\` or `/` with `.`
+- Remove all duplications in the path. For example, the path `virtualNetwork/virtualNetworkPeerings` would be shortened to `virtualNetwork/peerings`
+
+**Examples**
+
+  - Vaults
+    - Before: `modules\Microsoft.RecoveryServices\vaults`
+    - After: `ms.recoveryservices.vaults`
+  - ReplicationProtectionContainerMappings
+    - Before: `modules\Microsoft.RecoveryServices\vaults\replicationFabrics\replicationProtectionContainers\replicationProtectionContainerMappings`
+    - After: `ms.recoveryservices.vaults.replicationfabrics.replicationprotectioncontainers.mappings`
+
+</details>
+
+<details>
+<summary>Private Bicep Registry (Azure Container Registry)</summary>
+
+**Actions**
+
+- Remove the root folder name `modules` from provided module reference
+- Make lowercase
+- Replace all `\` or `/` with `.`
+- Add the `bicep/modules` prefix
+
+**Examples**
+
+- Vaults
+   - Before: `modules\Microsoft.RecoveryServices\vaults`
+   - After: `bicep/modules/microsoft.recoveryservices.vaults`
+- ReplicationProtectionContainerMappings
+   - Before: `modules\Microsoft.RecoveryServices\vaults\replicationFabrics\replicationProtectionContainers\replicationProtectionContainerMappings`
+   - After: `bicep/modules/microsoft.recoveryservices.vaults.replicationfabrics.replicationprotectioncontainers.replicationprotectioncontainermappings`
+
+</details>
+
+<details>
+<summary>Azure DevOps Universal Packages</summary>
+
+**Actions**
+
+- Remove the root folder name `modules` from provided module reference
+- Make lowercase
+- Replace all `\` or `/` with `.`
+
+**Examples**
+
+- Vaults
+  - Before: `modules\Microsoft.RecoveryServices\vaults`
+  - After: `microsoft.recoveryservices.vaults`
+- ReplicationProtectionContainerMappings
+  - Before: `modules\Microsoft.RecoveryServices\vaults\replicationFabrics\replicationProtectionContainers\replicationProtectionContainerMappings`
+  - After: `microsoft.recoveryservices.vaults.replicationfabrics.replicationprotectioncontainers.replicationprotectioncontainermappings`
+
+</details>
+
+<p>
+
 # How it works
 
 The publishing works as follows:
@@ -36,6 +105,7 @@ The publishing works as follows:
          > Example: Using the Bicep registry, the reference to a `major.minor` could look like: `br/modules:microsoft.resources.resourcegroups:0.4` which means that the template will always consume whatever the potentially overwritten/updated version `0.4` contains.
    1. For a changed child module, the direct parent hierarchy is also registered for an update, following the same procedure as above.
    1. The list of module files paths and their versions are passed on as a array list.
+1. The [Get-ModulesMissingFrom*.ps1](https://github.com/Azure/ResourceModules/tree/main/utilities/pipelines/resourcePublish) scripts further check if a given module is missing from the corresponding target location (e.g., Azure Container Registry) and adds each missing entry to to aforementioned array - using the version specified in the module's `version.json` file.
 1. The different publishing scripts run (Artifact, Template Spec or Bicep Registry) and publish the module to the respective target location for each item on the list.
 
 ## Example scenario

utilities/pipelines/resourcePublish/Get-TemplateSpecsName.ps1

@@ -23,7 +23,29 @@ function Get-TemplateSpecsName {
 
     $moduleIdentifier = (Split-Path $TemplateFilePath -Parent).Replace('\', '/').Split('/modules/')[1]
     $templateSpecIdentifier = $moduleIdentifier.Replace('\', '/').Replace('/', '.').ToLower()
-
+    $templateSpecIdentifier = $templateSpecIdentifier -replace 'microsoft', 'ms'
+
+    # Shorten the name
+    # This is requried as certain modules generate names such as `MS.RecoveryServices.vaults.replicationFabrics.replicationProtectionContainers.replicationProtectionContainerMappings` which are longer than the allowed 90 characters for template specs
+    # Using the logic below, the name is shortened to `MS.RecoveryServices.vaults.replicationFabrics.replicationProtectionContainers.Mappings` which has 'only' 86 characters
+    $nameElems = $templateSpecIdentifier -split '\.'
+    for ($index = 0; $index -lt $nameElems.Count; $index++) {
+        if ($index -lt ($nameElems.count - 1)) {
+            $stringToRemove = $nameElems[($index)]
+            $stringToCheck = $nameElems[($index + 1)]
+
+            if ($stringToRemove.EndsWith('s') -and $stringToCheck.StartsWith($stringToRemove.Substring(0, $stringToRemove.length - 1))) {
+                $singularString = $stringToRemove.Substring(0, $stringToRemove.length - 1)
+                $rest = $stringToCheck.length - $singularString.Length
+                $shortenedString = $stringToCheck.Substring($singularString.length, $rest)
+                $camelCaseString = [Regex]::Replace($shortenedString , '\b.', { $args[0].Value.Tolower() })
+                $nameElems[($index + 1)] = $camelCaseString
+            } elseif ($stringToCheck.StartsWith($stringToRemove)) {
+                $nameElems[($index + 1)] = $stringToCheck.Substring($stringToRemove.length, $stringToCheck.length)
+            }
+        }
+    }
+    $templateSpecIdentifier = $nameElems -join '.'
 
     return $templateSpecIdentifier
 }

utilities/pipelines/resourcePublish/Get-UniversalArtifactsName.ps1

@@ -24,7 +24,7 @@ function Get-UniversalArtifactsName {
 
     $ModuleFolderPath = Split-Path $TemplateFilePath -Parent
     $universalPackageModuleName = $ModuleFolderPath.Replace('\', '/').Split('/modules/')[1]
-    $universalPackageModuleName = ($universalPackageModuleName.Replace('\', '.').Replace('/', '.').toLower() -Replace '[^a-z0-9\.\-_]')[0..255] -join ''
+    $universalPackageModuleName = $universalPackageModuleName.Replace('\', '.').Replace('/', '.').toLower()
 
     return $universalPackageModuleName
 }