Ensure legacy migrators are inserted at the beginning of the collection

[ronaldbarendse]

While testing importing legacy Umbraco 7 content and schema into v16, I noticed it's become a little harder in recent versions to ensure the migrators are added in the correct order, because Deploy now adds quite a few migrators by default (e.g. to migrate property editors that were removed in v14, like Nested Content and Grid layout).

To ensure the legacy migrators are added before the default Deploy ones, you need to add them in a composer that runs before the Deploy one (which is different between Deploy Cloud and OnPrem). It's also important to add your own migrators after the Deploy ones (especially migrators like ReplaceUnknownEditorDataTypeArtifactMigrator, so Nested Content isn't replaced with a label), requiring you to use different composers:

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Cloud;
using Umbraco.Deploy.Infrastructure.Migrators;

[ComposeBefore(typeof(UmbracoDeployCloudComposer))]
//[ComposeBefore(typeof(UmbracoDeployOnPremComposer))]
internal sealed class LegacyDeployMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactTypeResolvers().AddLegacyTypeResolver();
        builder.DeployArtifactMigrators().AddLegacyMigrators();
        builder.DeployPropertyTypeMigrators().AddLegacyMigrators();
    }
}

[ComposeAfter(typeof(UmbracoDeployCloudComposer))]
//[ComposeAfter(typeof(UmbracoDeployOnPremComposer))]
internal sealed class DeployMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactMigrators()
            .Append<ReplaceMediaPickerDataTypeArtifactMigrator>()
            .Append<ReplaceNestedContentDataTypeArtifactMigrator>()
            .Append<ReplaceUnknownEditorDataTypeArtifactMigrator>();

        builder.DeployPropertyTypeMigrators()
            .Append<MediaPickerPropertyTypeMigrator>()
            .Append<NestedContentPropertyTypeMigrator>();
    }
}

To fix this, I've updated the AddLegacyMigrators() methods to insert the required artifact and property type migrators (and aligned AddLegacyTypeResolver()` to insert as well).

[Copilot]

Pull Request Overview

This PR modifies the legacy migrator registration methods to insert migrators at the beginning of the collection instead of appending them at the end, ensuring they execute before default Deploy migrators when importing Umbraco 7 content and schema.

• Changed AddLegacyMigrators() methods to use Insert() instead of Append() for proper execution order
• Added a new utility class OrderedCollectionBuilderExtensions to support inserting multiple types at once
• Updated documentation to clarify the insertion behavior and its importance

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
PropertyTypeMigratorCollectionBuilderExtensions.cs	Updated to insert legacy property type migrators at collection start
OrderedCollectionBuilderExtensions.cs	New utility class providing Insert methods for collection builders
ArtifactTypeResolverCollectionBuilderExtensions.cs	Updated to insert legacy artifact type resolver at collection start
ArtifactMigratorCollectionBuilderExtensions.cs	Updated to insert legacy artifact migrators at collection start

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}