Registro de una herramienta externa

  • Artículo

Algunas herramientas deben registrarse manualmente con Power BI Desktop. Para registrar una herramienta externa, cree un archivo JSON con el código de ejemplo siguiente:

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

El archivo pbitool.json incluye los siguientes elementos:

  • name: proporcione un nombre para la herramienta, que aparecerá como un título de botón en la cinta de opciones Herramientas externas en Power BI Desktop.
  • description: (opcional) proporcione una descripción que aparecerá como información sobre herramientas en el botón de la cinta de opciones Herramientas externas en Power BI Desktop.
  • path: proporcione la ruta de acceso completa al archivo ejecutable de la herramienta.
  • arguments: (opcional) proporcione una cadena de argumentos de la línea de comandos con los que se debe iniciar el archivo ejecutable de la herramienta. Puede usar cualquiera de los siguientes marcadores de posición:
    • %server%: se reemplaza por el nombre del servidor y el número de puerto de la instancia local del modelo tabular de Analysis Services para los modelos de datos importados/DirectQuery.
    • %database%: se reemplaza por el nombre de base de datos del modelo hospedado en la instancia local del modelo tabular de Analysis Services para los modelos de datos importados/DirectQuery.
  • iconData: proporcione datos de imagen, que se representarán como un icono de botón en la cinta de Herramientas externas en Power BI Desktop. Se debe dar formato a la cadena según la sintaxis de los URI de datos sin el prefijo "data:".

Asigne al archivo el nombre "<tool name>.pbitool.json" y colóquelo en la siguiente carpeta:

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

En entornos de 64 bits, coloque los archivos en la siguiente carpeta:

  • Archivos de programa (x86)\Common Files\Microsoft Shared\Power BI Desktop\External Tools

Los archivos de la ubicación especificada con la extensión .pbitool.json se cargan en Power BI Desktop cuando se inicia.

Ejemplo

El siguiente archivo *.pbitool.json inicia powershell.exe desde la cinta de herramientas externas y ejecuta un script denominado pbiToolsDemo.ps1. El script pasa el nombre del servidor y el número de puerto en el parámetro "Server" y el nombre del modelo semántico en el parámetro "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" 
}

El script de pbiToolsDemo.ps1 correspondiente genera los parámetros Server y Database en la consola.

[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 de datos de iconos

Para incluir un icono en la cinta de opciones de herramientas externas, el archivo de registro pbitool.json debe incluir un elemento iconData.

Screenshot of the external tools ribbon with the tool icons.

El elemento iconData toma un URI de datos sin el prefijo data: . Por ejemplo, el URI de datos de una imagen png de un píxel magenta es:

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

Asegúrese de quitar el prefijo data:, tal como se muestra en el ejemplo anterior de pbitool.json.

Para convertir un archivo .png u otro tipo de archivo de imagen en un URI de datos, use una herramienta en línea o una herramienta personalizada, como la que se muestra en el siguiente fragmento de código de 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(); 
}

Contenido relacionado