Registrare uno strumento esterno

  • Articolo

Alcuni strumenti devono essere registrati manualmente con Power BI Desktop. Per registrare uno strumento esterno, creare un file JSON con il codice di esempio seguente:

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

Il file pbitool.json include gli elementi seguenti:

  • nome:specificare un nome per lo strumento, che comparirà come nome di un pulsante nella barra multifunzione Strumenti esterni di Power BI Desktop.
  • description: (facoltativo) specificare una descrizione, che verrà visualizzata come descrizione comando nel pulsante della barra multifunzione Strumenti esterni in Power BI Desktop.
  • path: specificare il percorso completo del file eseguibile dello strumento.
  • arguments: (facoltativo) specificare una stringa di argomenti della riga di comando con i quali deve essere avviato il file eseguibile dello strumento. È possibile usare uno dei segnaposto seguenti:
    • %server%: sostituito con il nome server e il numero di porta dell'istanza locale di Analysis Services Tabular per i modelli di dati importati/DirectQuery.
    • %database%: sostituito con il nome database del modello ospitato nell'istanza locale di Analysis Services Tabular per i modelli di dati importati/DirectQuery.
  • iconData: specificare i dati immagine di cui verrà eseguito il rendering come icona di pulsante nella barra multifunzione Strumenti esterni in Power BI Desktop. La stringa deve essere formattata in base alla sintassi per gli URI di dati senza il prefisso "data:".

Assegnare al file il nome "<tool name>.pbitool.json" e inserirlo nella cartella seguente:

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

Per gli ambienti a 64 bit, inserire i file nella cartella seguente:

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

I file nel percorso specificato con l'estensione .pbitool.JSON vengono caricati da Power BI Desktop all'avvio.

Esempio

Il file *.pbitool.json seguente avvia powershell.exe dalla barra multifunzione Strumenti esterni ed esegue uno script denominato pbiToolsDemo.ps1. Lo script passa il nome del server e il numero di porta nel parametro -Server e il nome del modello semantico nel parametro -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" 
}

Lo script pbiToolsDemo.ps1 corrispondente restituisce i parametri Server e Database nella console.

[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 dell'output della console di PowerShell creato dallo strumento esterno di esempio.

URI dati icona

Per includere un'icona nella barra multifunzione Strumenti esterni, il file di registrazione pbitool.json deve includere un elemento iconData.

Screenshot della barra multifunzione degli strumenti esterni con le icone degli strumenti.

L'elemento iconData accetta un URI di dati senza il prefisso dati:. Ad esempio, l'URI dati di un'immagine png magenta di un pixel è:

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

Accertarsi di rimuovere i dati: prefisso, come illustrato nell'esempio precedente pbitool.json.

Per convertire un .png o un altro tipo di file di immagine in un URI dati, usare uno strumento online o uno strumento personalizzato, come ad esempio quello illustrato nel frammento di codice C# seguente:

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(); 
}

Contenuto correlato