OperationResult

升级工具箱时单个操作的状态

自 R2019b 起

说明

OperationResult 对象表示升级工具箱的个人设置时单个操作的状态。

创建对象

使用 matlab.settings.loadSettingsCompatibilityResults 函数为特定工具箱版本号创建一个 ReleaseCompatibilityResults 对象。ReleaseCompatibilityResults 对象的 Results 属性包含 VersionResults 对象。该 VersionResults 对象的 VersionChanges 属性包含 OperationResult 对象数组。

例如，以下代码获取工具箱 mytoolbox 版本 2 的 OperationResult 对象数组。

myCompatibilityResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
myCompatibilityResults.Results.VersionChanges

ans = 
  1×2 OperationResult array with properties:
    Operation
    Status
    ExceptionLog

属性

全部展开

`Operation` — 执行的升级操作
字符串标量

执行的升级操作，指定为字符串标量。

示例: "move mytoolbox.font.MyFontSize mytoolbox.font.FontSize"

`Status` — 升级操作的状态
`"Succeeded"` | `"Skipped"` | `"Failed"`

升级操作的状态，指定为 "Succeeded"、"Skipped" 或 "Failed"。下表列出了各种状态及其可能的原因。

状态	原因
`"Succeeded"`	不适用
`"Skipped"`	要升级的个人设置中不存在操作中指定的设置或设置组。
`"Failed"`	移动操作	升级的设置树已包含具有指定名称的设置或设置组。指定的设置或设置组路径不是有效路径。
`"Failed"`	删除操作	指定的设置或设置组路径不是有效路径。

`ExceptionLog` — 第一个升级异常
`ReleaseCompatibilityException` 对象 | 0×0 `ReleaseCompatibilityException` 对象数组

执行升级操作时出现的第一个升级异常，指定为 ReleaseCompatibilityException 对象。如果没有异常发生，ExceptionLog 是 ReleaseCompatibilityException 对象的 0×0 数组。

示例

全部折叠

获取升级个人设置的结果

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

函数 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"
}

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

matlab.settings.reloadFactoryFile('mytoolbox');

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

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

将 createMyToolboxFactoryTree 中的设置名称从 MyFontSize 和 MyFontColor 更改为 FontSize 和 FontColor。

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 的设置树的更改。

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

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

matlab.settings.reloadFactoryFile('mytoolbox');

使用 settings 函数访问设置树的根，并验证 FontSize 设置的个人值是否已从 MyFontSize 设置中正确移出。

s = settings;
s.mytoolbox.font.FontSize

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

获取 mytoolbox 版本 2 的第一个升级操作结果。

compatibilityResults.matlab.settings.loadSettingsCompatibilityResults("mytoolbox","Version2");
compatibilityResults.Results.VersionChanges(1)

ans = 
  OperationResult with properties:
       Operation: "move mytoolbox.font.MyFontSize mytoolbox.font.FontSize"
          Status: "Succeeded"
    ExceptionLog: [0×0 matlab.settings.ReleaseCompatibilityException]