Migrate Steps and Custom Apis to new assembly with a fully automated process

If a plugin-type needs to be renamed or removed completely in a Dataverse environment it is necessary to take some additional steps to make sure that managed solution deployments that incorporate the removal/rename of a plugin-type are still successful. As manually updating all steps and APIs to the new assembly can be tedious and error-prone we’ll come up with a fully automated process.

Simply removing or renaming a plugin-type causes error

Imagine you have a plugin assembly with a plugin-type called Plugins.SamplePlugin1 and Plugins.SamplePlugin2. If you decide to remove/rename plugin-type Plugins.SamplePlugin2 from the assembly and try to update the assembly content, you are presented with the error below:

Plug-in assembly does not contain the required types or assembly content cannot be updated.

The probably tempting approach is to just delete the plugin-type with Plugin Registration Tool. While this would work in an unmanaged scenario it will definitly fail once you move to the next stage in a managed solution and try the very same thing upfront in a pre-deployment task. Only the error message differs:

The evaluation of the current component(name=SdkMessageProcessingStep, id=XXX) in the current operation (Delete) failed during managed property evaluation of condition: {Managed Property Name: ismanaged}

Solution: Steps and custom-api need to reference the new assembly

So what is the solution? To correctly remove the plugin-type it is required to bump the assembly version on the first two digits (major.minor.build.revision), while third and fourth do not change assembly handling from a Dataverse standpoint.

After that you cannot do an in-place update but have to re-register that assembly as new and fresh assembly.

You end up with a new registered assembly without any steps associated. Furthermore, in case you have custom APIs defined, those will also reference the plugin-types in the original plugin assembly.

An automated solution for removing or renaming plugin-types

Before you now think about updating the plugin steps and custom apis by hand we will provide you with a programmatic approach to updating the steps and custom-apis to the plugin-types in the new assembly.

• Line 4: Change the assembly name
• Line 5: Change the original version number
• Line 6: Change the new version number

When you run the method MigrateStepsAndApisToNewAssemblyVersion it will look for the assemblies in the given version number and update the associated plugin-types and apis to use the new assembly.

For diagnostic purposes new plugin-types as well as plugin-types that are not present in the new assembly are documented in lines 81/85.

static async Task Main(string[] args)
{
    using var serviceClient = new ServiceClient("ADD-YOUR-CONNECTIONSTRING");
    const string assemblyName = "Pragdev.Sample.Plugins";
    var firstVersion = "2.0.0.0";
    var secondVersion = "3.0.0.0";

    await MigrateStepsAndApisToNewAssemblyVersion(serviceClient, assemblyName, firstVersion, secondVersion);
}

private static async Task MigrateStepsAndApisToNewAssemblyVersion(ServiceClient serviceClient, string assemblyName, string firstVersion, string secondVersion)
{
    // Get assembly by name
    var assemblies = await serviceClient.RetrieveMultipleAsync(new QueryExpression("pluginassembly")
    {
        ColumnSet = new ColumnSet("version"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("name", ConditionOperator.Equal, assemblyName),
            }
        }
    });

    if (assemblies.Entities.Count == 0)
    {
        Console.WriteLine("Assembly {0} not found.", assemblyName);
    }

    var firstVersionAssembly = assemblies.Entities
        .FirstOrDefault(a => string.Equals(a.GetAttributeValue<string>("version"), firstVersion));

    if (firstVersionAssembly == null)
    {
        Console.WriteLine("Assembly {0} not found in version {1}.", assemblyName, firstVersion);
    }

    var secondVersionAssembly = assemblies.Entities
        .FirstOrDefault(a => string.Equals(a.GetAttributeValue<string>("version"), secondVersion));

    if (secondVersionAssembly == null)
    {
        Console.WriteLine("Assembly {0} not found in version {1}.", assemblyName, secondVersion);
    }

    Console.WriteLine("Searching for types in version {0}.", firstVersion);
    var typesFirst = await serviceClient.RetrieveMultipleAsync(new QueryExpression("plugintype")
    {
        ColumnSet = new ColumnSet("typename"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("pluginassemblyid", ConditionOperator.Equal, firstVersionAssembly.Id),
            }
        }
    });

    Console.WriteLine("Found {0} types in first assembly.", typesFirst.Entities.Count);

    Console.WriteLine("Searching for types in version {0}.", secondVersion);
    var typesSecond = await serviceClient.RetrieveMultipleAsync(new QueryExpression("plugintype")
    {
        ColumnSet = new ColumnSet("typename"),
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression("pluginassemblyid", ConditionOperator.Equal, secondVersionAssembly.Id),
            }
        }
    });
    Console.WriteLine("Found {0} types in second assembly.", typesSecond.Entities.Count);


    var typeNamesInFirst = typesFirst.Entities.Select(e => e.GetAttributeValue<string>("typename")).OrderBy(x => x).ToList();
    var typeNamesInSecond = typesSecond.Entities.Select(e => e.GetAttributeValue<string>("typename")).OrderBy(x => x).ToList();

    var typesMissingInNewAssembly = typeNamesInFirst.Except(typeNamesInSecond, StringComparer.InvariantCultureIgnoreCase).ToList();
    Console.WriteLine("Types missing in new Assembly: {0}", typesMissingInNewAssembly.Any() ? string.Join(", ", typesMissingInNewAssembly) : "none");


    var typesNewlyCreatedInNewAssembly = typeNamesInSecond.Except(typeNamesInFirst, StringComparer.InvariantCultureIgnoreCase).ToList();
    Console.WriteLine("Types newly created in new Assembly: {0}", typesNewlyCreatedInNewAssembly.Any() ? string.Join(", ", typesNewlyCreatedInNewAssembly) : "none");

    foreach (var pluginType in typesSecond.Entities)
    {
        var typeName = pluginType.GetAttributeValue<string>("typename");

        if(!typeName.Contains("preserve", StringComparison.OrdinalIgnoreCase))
        {
            continue;
        }

        Console.WriteLine("Analyzing plugintype: " + typeName);

        var typeInBothAssemblies = typesFirst.Entities
            .FirstOrDefault(pt =>
                string.Equals(pt.GetAttributeValue<string>("typename"), typeName, StringComparison.OrdinalIgnoreCase));


        if (typeInBothAssemblies != null)
        {
            var stepsFirst = await serviceClient.RetrieveMultipleAsync(
                new QueryExpression("sdkmessageprocessingstep")
                {
                    ColumnSet = new ColumnSet(),
                    Criteria =
                    {
                        Conditions =
                        {
                            new ConditionExpression("plugintypeid", ConditionOperator.Equal, typeInBothAssemblies.Id),
                            new ConditionExpression("category", ConditionOperator.NotEqual, "CustomAPI"),
                        }
                    }
                });

            Console.WriteLine("Found {0} steps for {1}.", stepsFirst.Entities.Count, typeName);

            foreach (var step in stepsFirst.Entities)
            {
                step["plugintypeid"] = pluginType.ToEntityReference();
                try
                {
                    await serviceClient.UpdateAsync(step);
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Error updating step {0} for type {1}", step.Id, typeName);
                    Console.WriteLine(ex.ToString());
                }
            }

            var apiFirst = await serviceClient.RetrieveMultipleAsync(
                new QueryExpression("customapi")
                {
                    ColumnSet = new ColumnSet(),
                    Criteria =
                    {
                        Conditions =
                        {
                            new ConditionExpression("plugintypeid", ConditionOperator.Equal, typeInBothAssemblies.Id),
                        }
                    }
                });

            Console.WriteLine("Found {0} apis for {1}.", apiFirst.Entities.Count, typeName);

            foreach (var api in apiFirst.Entities)
            {
                api["plugintypeid"] = pluginType.ToEntityReference();
                try
                {
                    await serviceClient.UpdateAsync(api);
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Error updating api {0} for type {1}", api.Id, typeName);
                    Console.WriteLine(ex.ToString());
                }
            }
        }
        else
        {
            Console.WriteLine("Plugintype: " + typeName + " is not contained in both assemblies.");
        }
    }
}

Conclusion

In this article we have walked through the process of renaming/removing a plugin-type in a Dataverse environment and correctly deploying your changes through managed solutions to the target environment. Furthermore, we automated the recurring tasks to prevent errors and make sure that steps and custom-apis reference the new assembly. I hope this approach will help you next time you need to update a plugin-assembly in your managed solution.