Parameters

Macro feature parameters might need to change from version to version. And SwEx.MacroFeature framework provides a mechanism to handle the backward compatibility of existing features.

Mark current version of parameters with ParametersVersionAttribute and increase the version if any of the parameters changed.

Implement the Paramater Version Converter to convert from the latest version of the parameters to the newest one. Framework will take care of aligning versions in case parameters are older than one version.

Old version of parameters

[ParametersVersion("1.0", typeof(MacroFeatureParamsVersionConverter))]
public class MacroFeatureParams
{
    public string Param1 { get; set; }
    public int Param2 { get; set; }
}

New version of parameters

[ParametersVersion("2.0", typeof(MacroFeatureParamsVersionConverter))]
public class MacroFeatureParams
{
    public string Param1A { get; set; }//parameter renamed
    public int Param2 { get; set; }
    public string Param3 { get; set; }//new parameter added
}

public class MacroFeatureParamsVersionConverter : ParametersVersionConverter
{
    private class VersConv_1_0To2_0 : ParameterConverter
    {
        public override Dictionary<string, string> ConvertParameters(IModelDoc2 model, IFeature feat, Dictionary<string, string> parameters)
        {
            var paramVal = parameters["Param1"];
            parameters.Remove("Param1");
            parameters.Add("Param1A", paramVal);//renaming parameter
            parameters.Add("Param3", "Default");//adding new parameter with default value
            return parameters;
        }
    }

    public ParamsMacroFeatureParamsVersionConverter()
    {
        //conversion from version 1.0 to 2.0
        Add(new Version("2.0"), new VersConv_1_0To2_0());
        //TODO: add more version converters
    }
}

If new dimensions have been added to the feature it is required to use the DisplayDimensionPlacholder within the ConvertDispayDimensions method.

In some cases framework is not able to convert some parameters. For example Icons and Dimensions cannot be converted. In this case SetParameters method will return the outdate state. If state is not up-to-date it is recommended to warn the user and call the IFeatureManager::ReplaceComFeature extension method which will replace feature in the tree preserving all the parameters.

Obsolete Feature

In some cases feature might become obsolete (i.e. no longer supported). Framework provides a mechanism to mark the feature as obsolete and allow replacement (if applicable).

  • To mark the feature as obsolete copy the class name, namespace, guid and prog id of the obsolete feature.
  • Mark the feature as COM visible
  • Inherit the class from ObsoleteMacroFeatureEx. If there s a replacement for this feature with the same model use this version of ObsoleteMacroFeatureEx and pass the model as a generic argument.
namespace CodeStack.SwEx.MacroFeature.Features
{
    [ComVisible(true), ProgId(PROG_ID), Guid("08a4ab5f-7b8a-44b5-a487-b44026a02c2b")]
    public class SomeOriginalFeature : ObsoleteMacroFeatureEx<MacroFeatureModel>
    {
        internal const string PROG_ID = "CodeStack.SomeOriginalFeature";
    }
}

When user rebuilds the feature it will be rebuilt with the following error:

Obsolete macro feature rebuild error
Obsolete macro feature rebuild error

When user clicks Edit Feature

Editing the obsolete feature
Editing the obsolete feature

The following message is displayed

Replacing obsolete feature
Replacing obsolete feature

If Yes is clicked the framework will automatically replace the obsolete feature with new one and copy all of the parameters (if applicable).