Main Content

本页采用了机器翻译。点击此处可查看英文原文。

使用命令行 API 更新或修复需求链接

此示例使用:

打开实时脚本

此示例涵盖了当一个或多个工件被移动或重命名后，设计工件和需求之间的链接变得过时的一组标准情况。我们不想删除断开的链接并创建新的链接，而是想更新现有的链接，以便保留创建/修改历史和其他属性（描述、关键字、注释等）。

示例工程文件

开始之前，请运行slreq.clear 命令以确保初始状态干净。然后打开 CruiseRequirementsExample 工程。这会将链接的工件文件集合解压到 MATLAB/Projects 文件夹下的新子文件夹中。

slreq.clear
openProject("CruiseRequirementsExample");

Simulink 模型与需求相关

我们将重点关注该工程依赖关系图的一小部分：打开 crs_plant.slx Simulink®模型，该模型有多个指向外部 Microsoft® Word 文档 crs_reqs.docx 的链接。

open_system('crs_plant');

导航其中一个链接来打开链接的文档。

rmi('view', 'crs_plant/status', 1);

Word文档打开到相应部分：

以下是如何使用命令行 API 并检查从 crs_plant.slx 到 crs_reqs.docx 的链接。

linkSet = slreq.find('type', 'LinkSet', 'Name', 'crs_plant');
links = linkSet.getLinks();
disp('Original Links to Word document:');
Original Links to Word document:

for i = 1:numel(links)
    linkTarget = links(i).getReferenceInfo();
    if contains(linkTarget.artifact, 'crs_req.docx')
        source = links(i).source;
        disp(['    found link from ' strrep(getfullname([bdroot source.id]),newline,'') ...
            ' to crs_req.docx']);
    end
end
    found link from crs_plant/Vehicle1/vehiclespeed to crs_req.docx
    found link from crs_plant/throttDrv to crs_req.docx
    found link from crs_plant/status to crs_req.docx
    found link from crs_plant/throttleCC to crs_req.docx

在存在导入引用的情况下导航直接链接

通过在 MATLAB® 命令行中输入 slreq.editor 打开需求编辑器。您将看到已加载两个需求集：crs_req.slreqx 和 crs_req_func_spec.slreqx。第一个需求集是从 crs_req.docx 导入的引用集合，第二个需求集是在需求编辑器中手动创建的。如果您现在关闭 Word 文档并从 crs_plant/status Inport 模块导航相同的链接，则相应的导入的引用将在需求编辑器中突出显示，因为导航操作在已加载的导入需求集中找到了匹配的引用。

updatelinks_importOriginal.png

您仍然可以使用在文档中显示按钮在原始文档的上下文中查看链接的需求。

slreq.editor();
rmidotnet.MSWord.application('kill');
rmi('view', 'crs_plant/status', 1);

用例 1：文档重命名后批量更新链接

假设收到了需求文档的更新版本，名为 crs_req_v2.docx。我们现在希望crs_plant.slx 中的链接指向更新文档的相应部分。为了本例的目的，我们将在同一文件夹中复制原始文档并修改其名称。然后，我们使用 slreq.LinkSet API 批量更新给定 LinkSet 中的所有链接，以连接到文档的较新副本：

copyfile(fullfile(pwd, 'documents/crs_req.docx'), fullfile(pwd, 'documents/crs_req_v2.docx'));
linkSet.updateDocUri('crs_req.docx', 'crs_req_v2.docx');

验证匹配链接的更新

现在我们可以浏览相同的链接并确认打开了外部文档的适当版本。如果我们像前面一样迭代所有链接，这可以确认所有 4 个链接均按预期更新：

rmi('view', 'crs_plant/status', 1); % updated document opens
links = linkSet.getLinks();
disp('Links to Word document after update:');
Links to Word document after update:

for i = 1:numel(links)
    source = links(i).source;
    linkTarget = links(i).getReferenceInfo();
    if contains(linkTarget.artifact, 'crs_req.docx')
        warning(['link from ' source.id ' still points to crs_req.docx']);  % should not happen
    elseif contains(linkTarget.artifact, 'crs_req_v2.docx')
        disp(['    found link from ' strrep(getfullname([bdroot source.id]),newline,' ')...
            ' to crs_req_v2.docx']);
    end
end
    found link from crs_plant/Vehicle1/vehicle speed to crs_req_v2.docx
    found link from crs_plant/throttDrv to crs_req_v2.docx
    found link from crs_plant/status to crs_req_v2.docx
    found link from crs_plant/throttleCC to crs_req_v2.docx

更新链接后导航至导入的参考文献

如上所示，当需求编辑器中提供了导入的引用时，导航链接将选择匹配的引用对象。但是，我们刚刚更新了文档crs_req_v2.docx新版本的链接，并且没有该文档的导入引用。在需求编辑器下从 Simulink 模块导航可将您直接带到外部 Word 文档。

为了避免这种不一致，我们需要更新先前导入的参考文献以便与更新的文档名称关联。我们使用slreq.ReqSet API来完成这项任务。此外，由于更新后的文档可能修改了需求，我们必须使用 updateFromDocument API 来提取存储在 Requirements Toolbox 端的引用项的更新。完成后，从 Simulink 模型导航将找到匹配的导入引用。

updatelinks_importOriginal.png

查找具有导入引用资料的需求集。更新源文件位置并找到顶级导入节点。 

reqSet = slreq.find('type', 'ReqSet', 'Name', 'crs_req');
reqSet.updateSrcFileLocation('crs_req.docx', 'crs_req_v2.docx'); 
importNode = reqSet.find('CustomId', 'crs_req_v2');

从源文件更新导入的引用。关闭 Microsoft Word。然后，导航到需求编辑器中更新的引用。

importNode.updateFromDocument();
rmidotnet.MSWord.application('kill');
rmi('view', 'crs_plant/status', 1);

用例 1 后的清理

放弃链接数据更改以避免工程关闭时出现提示。关闭工程（也清理 MATLAB 路径更改）。关闭 Microsoft Word。

slreq.clear();                        
prj = simulinkproject(); prj.close();
rmidotnet.MSWord.application('kill');

用例 2：批量更新链接以完全依赖导入的引用

如上面的用例 1 所示，当文档被移动或重命名时，需要付出额外的努力来维护与外部文档的“直接链接”。更好的工作流程是将现有的“直接链接”转换为“引用链接”，这些链接指向 *.slreqx 文件中导入的 References，并且不再重复有关原始文档位置或名称的信息。使用此选项时，外部源文档关联仅存储在承载导入引用的需求集中。

为了演示此工作流程，请通过在新的子文件夹中重新打开 CruiseRequirementsExample 工程从同一初始点重新启动。将 Simulink 模型复制到您的目录并打开它。

openProject("CruiseRequirementsExample");
copyfile(fullfile(pwd, 'documents/crs_req.docx'), fullfile(pwd, 'documents/crs_req_v2.docx'));
open_system('crs_plant');

使用导入的引用资料查找crs_plant链接集和crs_req需求集。

linkSet = slreq.find('type', 'LinkSet', 'Name', 'crs_plant');
reqSet = slreq.find('type', 'ReqSet', 'Name', 'crs_req');

然后我们使用 slreq.LinkSet API 来更新 crs_plant.slmx 中的所有直接链接。然后创建链接集中所有链接的数组。

linkSet.redirectLinksToImportedReqs(reqSet);
links = linkSet.getLinks();

以此方式更新LinkSet后，循环遍历所有链接以确认不存在指向crs_req.docx文件的“直接”链接。

disp('Check for links to original external document:');
Check for links to original external document:

counter = 0;
for i = 1:numel(links)
    linkTarget = links(i).getReferenceInfo();
    if contains(linkTarget.artifact, 'crs_req.docx')
        source = links(i).source;
        warning(['link from ' source.id ' still points to crs_req.docx']);
        counter = counter + 1;
    end
end
disp(['    Total ' num2str(counter) ' links to external document']);
    Total 0 links to external document

从 Simulink 模型导航到更新的引用。

rmi('view', 'crs_plant/status', 1);

参考文献链接和外部文档重命名

现在，当所有链接指向导入的参考文献而不是外部文档时，只要导入节点针对新的外部文档名称进行了更新，可追溯性数据在文档重命名后仍保持一致。与用例 1 一样，我们将假装存在外部需求文档的更新版本，通过使用新名称重新保存我们的 Word 文档。然后，我们使用与之前相同的 API 对导入节点执行所需的更新。现在，由于链接依赖于导入的引用，并且不存储有关导入文档的信息，从 Simulink模型导航将带我们到更新的引用，与执行用例 1 的所有步骤后相同。

updatelinks_importOriginal.png

该引用现在与更新的外部文档相关联，[在文档中显示]按钮打开更新的（重命名的）文档，并且不需要在 LinkSet 端进行进一步调整。

查找具有导入引用资料的需求集。更新源文件位置并找到顶级导入节点。 

reqSet = slreq.find('type', 'ReqSet', 'Name', 'crs_req');
reqSet.updateSrcFileLocation('crs_req.docx', 'crs_req_v2.docx'); 
importNode = reqSet.find('CustomId', 'crs_req_v2');

从源文件更新导入的引用。然后，导航到需求编辑器中更新的引用。

importNode.updateFromDocument();
rmi('view', 'crs_plant/status', 1);

用例 2 后的清理

放弃链接数据更改以避免工程关闭时出现提示。关闭工程（也清理 MATLAB 路径更改）。关闭 Microsoft Word。

slreq.clear();                        
prj = simulinkproject(); prj.close();
rmidotnet.MSWord.application('kill');

用例 3：将链接的工件移动到新工程

现在假设我们正在对一个具有链接工件的现有工程进行分支，并且我们需要创建一组新的重命名工件，其中包含与原始工程相同的所有可追溯性链接。与之前一样，我们将 CruiseRequirementsExample 工程提取到一个新的子文件夹中，并将“直接链接”转换为“引用链接”，就像我们在上面的用例 2 中所做的那样。然后，我们继续创建链接工件的“新版本”，通过使用 _v2. 名称重新保存每个工件。

在创建 Simulink模型、导入的外部文档和包含导入需求的需求集的重命名副本后，出现一个问题：重命名的模型链接到原始需求集中的引用，而不是重命名的需求集中的引用。在详细信息窗格中的链接下，链接显示为未解析，因为未加载原始模型。

updatelinks_oldReference.png

打开CruiseRequirementsExample工程并打开crs_plant模型。找到 crs_plant 的链接集和需求集crs_req。

openProject("CruiseRequirementsExample");
open_system('models/crs_plant.slx');
linkSet = slreq.find('type', 'LinkSet', 'Name', 'crs_plant');
reqSet = slreq.find('type', 'ReqSet', 'Name', 'crs_req');

将直接链接转换为引用链接。创建文件的重命名副本并保存。

linkSet.redirectLinksToImportedReqs(reqSet);     
mkdir(fullfile(pwd, 'copied'));
save_system('crs_plant', fullfile(pwd, 'copied/crs_plant_v2.slx'));  
reqSet.save(fullfile(pwd, 'copied/crs_req_v2.slreqx'));              
copyfile('documents/crs_req.docx', 'copied/crs_req_v2.docx');

将重命名的需求集与重命名的文档关联。找到顶级导入节点。

reqSet.updateSrcFileLocation('crs_req.docx', fullfile(pwd, 'copied/crs_req_v2.docx'));
importNode = reqSet.find('CustomId', 'crs_req_v2');

通过更新导入的参考文献，确保重命名的需求集集中的内容与重命名的文档的内容相匹配。从重命名的 Simulink模型导航到重命名的需求集集中的项目。原始需求集集中的旧项目被突出显示，这是不正确的。

importNode.updateFromDocument();
rmi('view', 'crs_plant_v2/status', 1);

更新重命名源中的链接以使用重命名的目标作为目标

与用例 1 类似，我们可以使用 LinkSet.updateDocUri(OLD, NEW) API 来更新 crs_plant_v2.slmx 中的链接，以使用重命名的需求集 crs_req_v2.slreqx 作为链接目标，而不是原来的 crs_req.slreqx。完成后，从重命名的模型中的模块再次导航。选定重命名的需求集中的需求，并解析右下角链接下的详细信息窗格中的链接。

updatelinks_updatedReference.png

找到模型新副本 crs_plant_v2 的链接集。更新与模型新副本相链接的需求集的名称。从重命名的 Simulink模型导航到重命名的需求集集中的项目。这一次，它突出显示了正确的项目。

linkSet = slreq.find('type', 'LinkSet', 'Name', 'crs_plant_v2');
linkSet.updateDocUri('crs_req.slreqx', 'crs_req_v2.slreqx');
rmi('view', 'crs_plant_v2/status', 1);