注册外部工具

  • 项目

某些工具必须通过 Power BI Desktop 进行手动注册。 若要注册外部工具，请创建包含以下示例代码的 JSON 文件：

{
    "name": "<tool name>",
    "description": "<tool description>",
    "path": "<tool executable path>",
    "arguments": "<optional command line arguments>",
    "iconData": "image/png;base64,<encoded png icon data>"
}

pbitool.json 文件包含以下元素：

  • name： 提供工具的名称，该名称将显示为 Power BI Desktop 中“外部工具”功能区中的按钮标题。
  • description：（可选）提供说明，它将在 Power BI Desktop 内的“外部工具”功能区按钮上显示为工具提示。
  • path：提供指向可执行文件的完全限定路径。
  • arguments：（可选）提供启动工具可执行文件时应使用的命令行参数字符串。 可以使用以下任意占位符：
    • %server%：替换为导入的/DirectQuery 数据模型的 Analysis Services 表格的本地实例的服务器名称和端口号。
    • %database%：替换为导入/DirectQuery 数据模型的 Analysis Services 表格本地实例中承载的模型的数据库名称。
  • iconData：提供图像数据，该数据将呈现为 Power BI Desktop 中“外部工具”功能区中的按钮图标。 应根据不带“data:”前缀的数据 URI 语法来设置字符串格式。

将该文件命名为 "<tool name>.pbitool.json" 并置于以下文件夹中：

  • %commonprogramfiles%\Microsoft Shared\Power BI Desktop\External Tools

对于 64 位环境，请将这些文件置于以下文件夹中：

  • Program Files (x86)\Common Files\Microsoft Shared\Power BI Desktop\External Tools

在启动时，Power BI Desktop 加载 .pbitool.json 扩展的指定位置中的文件。

示例

以下 *.pbitool.json 文件从“外部工具”功能区启动 powershell.exe，并运行名为 pbiToolsDemo.ps1 的脚本。 该脚本在 -Server 参数中传递服务器名称和端口号，在 -Database 参数中传递语义模型名称。

{ 
    "version": "1.0.0", 
    "name": "External Tools Demo", 
    "description": "Launches PowerShell and runs a script that outputs server and database parameters. (Requires elevated PowerShell permissions.)", 
    "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", 
    "arguments": "C:\\pbiToolsDemo.ps1 -Server \"%server%\" -Database \"%database%\"", 
    "iconData": "image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsEAAA7BAbiRa+0AAAANSURBVBhXY/jH9+8/AAciAwpql7QkAAAAAElFTkSuQmCC" 
}

相应的 pbiToolsDemo.ps1 脚本会将 Server 和 Database 参数输出到控制台。

[CmdletBinding()] 
param 
( 
        [Parameter(Mandatory = $true)]         
[string] $Server, 
        [Parameter(Mandatory = $true)]         
[string] $Database  
) 
Write-Host "" 
Write-Host "Analysis Services instance: " -NoNewline 
Write-Host "$Server" -ForegroundColor Yellow 
Write-Host "Dataset name: " -NoNewline 
Write-Host "$Database" -ForegroundColor Green 
Write-Host "" 
Read-Host -Prompt 'Press [Enter] to close this window'

Screenshot of PowerShell console output created from the example external tool.

图标数据 URI

若要将图标包含在“外部工具”功能区中，pbitool.json 注册文件必须包含 iconData 元素。

Screenshot of the external tools ribbon with the tool icons.

iconData 元素采用不带 data: 前缀的数据 URI。 例如，一个像素的洋红色 png 图像的数据 URI 如下所示：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsEAAA7BAbiRa+0AAAANSURBVBhXY/jH9+8/AAciAwpql7QkAAAAAElFTkSuQmCC

请务必删除 data: 前缀，如上述 pbitool.json 示例所示。

若要将 .png 或其他图像文件类型转换为数据 URI，请使用在线工具或自定义工具，如以下 C# 代码片段所示：

string ImageDataUri; 
OpenFileDialog openFileDialog1 = new OpenFileDialog(); 
openFileDialog1.Filter = "PNG Files (.png)|*.png|All Files (*.*)|*.*"; 
openFileDialog1.FilterIndex = 1; 
openFileDialog1.Multiselect = false; 
openFileDialog1.CheckFileExists = true; 
bool? userClickedOK = openFileDialog1.ShowDialog(); 
if (userClickedOK == true) 
{ 
    var fileName = openFileDialog1.FileName; 
    var sb = new StringBuilder(); 
    sb.Append("image/") 
        .Append((System.IO.Path.GetExtension(fileName) ?? "png").Replace(".", "")) 
        .Append(";base64,") 
        .Append(Convert.ToBase64String(File.ReadAllBytes(fileName))); 
    ImageDataUri = sb.ToString(); 
}

相关内容