Main Content

ReleaseCompatibilityException

升级工具箱时发生的异常

说明

ReleaseCompatibilityException 对象表示在升级工具箱的个人设置时发生的异常。

创建对象

使用 matlab.settings.loadSettingsCompatibilityResults 函数为特定工具箱版本号创建一个 ReleaseCompatibilityResults 对象。访问 PreValidationExceptions 属性可获取 ReleaseCompatibilityException 对象的数组。

例如,以下代码以 ReleaseCompatibilityException 对象的数组形式获取工具箱 mytoolbox 的版本 2 的预验证异常。

myCompatibilityResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
myCompatibilityResults.PreValidationExceptions
ans = 
  0×0 ReleaseCompatibilityException array with properties:
    ExceptionString
    ExceptionID

属性

全部展开

异常消息,指定为字符向量。如果发生异常,ExceptionString 包含异常消息。

示例: ''font.FontSize' is an invalid path for adding a new group. The path needs to be relative to the master settings file and cannot contain ".." between folder names.'

异常标识符,指定为字符串标量。如果发生异常,ExceptionID 包含异常的标识符。

示例: "MATLAB:settings:config:PathNotRelativeToMasterFile"

示例

全部折叠

创建函数来创建一个工具箱出厂树,然后升级该工具箱出厂树,再测试升级是否成功完成。

函数 createMyToolboxFactoryTree,该函数为工具箱 mytoolbox 创建出厂设置树。

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'MyFontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'MyFontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

使用空的 matlab.settings.SettingsFileUpgrader 对象创建函数 createMyToolboxSettingsFileUpgraders

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader.empty;
end

为工具箱创建 settingsInfo.json 文件。指定 mytoolbox 为根设置组名称,createMyToolboxFactoryTree 为设置树创建函数,createMyToolboxSettingsFileUpgraders 为设置树升级函数。将 settingsInfo.json 放入工具箱 resources 文件夹中。

{
"ToolboxGroupName" : "mytoolbox",
"Hidden" : false,
"CreateTreeFcn" : "createMyToolboxFactoryTree",
"CreateUpgradersFcn" : "createMyToolboxSettingsFileUpgraders"
}

将包含设置树创建函数和工具箱 resources 文件夹的文件夹添加到 MATLAB® 路径。然后,加载 mytoolbox 的出厂设置树。

matlab.settings.reloadFactoryFile('mytoolbox');

使用 settings 函数访问设置树的根,并为 MyFontSize 设置设置个人值。

s = settings;
s.mytoolbox.font.MyFontSize.PersonalValue = 15;

createMyToolboxFactoryTree 中的设置名称从 MyFontSizeMyFontColor 更改为 FontSizeFontColor

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'FontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

createMyToolboxSettingsFileUpgraders 函数中两个设置的重命名记录为对 mytoolbox 的版本 2 的设置树的更改。在记录两个设置的重命名时,在其中一条路径中会引入错误。例如,从第一个记录的更改的目标路径中删除 mytoolbox

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2'); 
    upgraders.move('mytoolbox.font.MyFontSize','font.FontSize'); 
    upgraders.move('mytoolbox.font.MyFontColor','mytoolbox.font.FontColor');
end

重新加载 mytoolbox 的出厂设置树。

matlab.settings.reloadFactoryFile('mytoolbox');

使用 settings 函数访问设置树的根,并验证 FontSize 设置的个人值。请注意,个人值没有被移动。

s = settings;
s.mytoolbox.font.FontSize
ans = 
  Setting 'mytoolbox.font.FontSize' with properties:
       ActiveValue: 11
    TemporaryValue: <no value>
     PersonalValue: <no value>
      FactoryValue: 11

获取 mytoolbox 的版本 2 的升级结果,并检查第一个操作的异常日志。

upgradeResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
upgradeResults.Results.VersionChanges(1).ExceptionLog
ans = 
  ReleaseCompatibilityException with properties:
    ExceptionString: ''font.FontSize' is an invalid path for adding a new group. 
                     The path needs to be relative to the master settings file 
                     and cannot contain ".." between folder names.'
        ExceptionID: "MATLAB:settings:config:PathNotRelativeToMasterFile"

版本历史记录

在 R2019b 中推出