Class ScriptHost
This is the host class in which a C# script is executed
Inherited Members
Namespace: TabularEditor.Shared.Scripting
Assembly: TabularEditor3.Shared.dll
Syntax
public class ScriptHost
Properties
Model
The currently loaded Model.
Declaration
public static Model Model { get; set; }
Property Value
Type | Description |
---|---|
Model |
Remarks
When no model is loaded in Tabular Editor, this property will be null causing calls to global methods such as EvaluateDax(string), SelectMeasure(Measure, string), etc. to fail. If you want to run a script without loading a model in Tabular Editor, or if you want the script to apply its changes to a different model than the one currently loaded, you may explicitly assign a model to this property as shown below:
Examples
var modelHandler = new TabularModelHandler("localhost", "AdventureWorks"); // Connects to the 'AdventureWorks' database from the 'localhost' AS instance Model = modelHandler.Model; // Specify that the script should use the model loaded above var myMeasure = SelectMeasure(); // Prompt the user to select a measure from the model.
Selected
An object that represents the current selection in the TOM Explorer.
Declaration
public static Selection Selected { get; }
Property Value
Type | Description |
---|---|
Selection |
WaitFormVisible
Toggle the "Please wait" spinner on/off. Useful if you want to display custom dialogs / UI to the end user.
Declaration
public static bool WaitFormVisible { get; set; }
Property Value
Type | Description |
---|---|
bool |
Remarks
Built-in script UI such as the Info(string, int) and SelectMeasure(IEnumerable<Measure>, Measure, string) functionality will automatically hide the "Please wait" spinner.
Methods
CallDaxFormatter(bool?, bool?)
Format all DAX expressions on objects currently flagged for formatting.
Declaration
public static void CallDaxFormatter(bool? shortFormat = null, bool? skipSpaceAfterFunctionName = null)
Parameters
Type | Name | Description |
---|---|---|
bool? | shortFormat | |
bool? | skipSpaceAfterFunctionName |
CollectVertiPaqAnalyzerStats()
Collects VertiPaq Analyzer statistics for the currently loaded model.
Declaration
public static void CollectVertiPaqAnalyzerStats()
ConvertDax(string, bool)
Changes the character used for decimals and list separators in a DAX expression.
Declaration
public static string ConvertDax(string dax, bool useSemicolons = true)
Parameters
Type | Name | Description |
---|---|---|
string | dax | The original DAX expression |
bool | useSemicolons | Set to true when converting from Non-US-style DAX to US-style DAX, or false for vice versa. |
Returns
Type | Description |
---|---|
string |
CustomAction(IEnumerable<ITabularNamedObject>, int)
Run a macro on a selection of objects. Alias for Macro(IEnumerable<ITabularNamedObject>, int)
Declaration
public static void CustomAction(IEnumerable<ITabularNamedObject> selection, int macroId)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<ITabularNamedObject> | selection | The object selection on which the macro should run. |
int | macroId | Id of the macro |
CustomAction(IEnumerable<ITabularNamedObject>, string)
Run a macro on a selection of objects. Alias for Macro(IEnumerable<ITabularNamedObject>, string)
Declaration
public static void CustomAction(IEnumerable<ITabularNamedObject> selection, string macroName)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<ITabularNamedObject> | selection | The object selection on which the macro should run. |
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
CustomAction(int)
Run a macro. Alias for Macro(int)
Declaration
public static void CustomAction(int macroId)
Parameters
Type | Name | Description |
---|---|---|
int | macroId | Id of the macro |
CustomAction(string)
Run a macro. Alias for Macro(string).
Declaration
public static void CustomAction(string macroName)
Parameters
Type | Name | Description |
---|---|---|
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
CustomAction(ITabularNamedObject, int)
Run a macro on an object. Alias for Macro(ITabularNamedObject, int)
Declaration
public static void CustomAction(ITabularNamedObject selection, int macroId)
Parameters
Type | Name | Description |
---|---|---|
ITabularNamedObject | selection | The object on which the macro should be run. |
int | macroId | Id of the macro |
CustomAction(ITabularNamedObject, string)
Run a macro on an object. Alias for Macro(ITabularNamedObject, string)
Declaration
public static void CustomAction(ITabularNamedObject selection, string macroName)
Parameters
Type | Name | Description |
---|---|---|
ITabularNamedObject | selection | The object on which the macro should be run. |
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
Error(string)
Displays an error message in a popup dialog. When the script is running in the CLI, an error message is written to the console.
Declaration
public static void Error(string message)
Parameters
Type | Name | Description |
---|---|---|
string | message |
EvaluateDax(string)
Evaluates the specified DAX expression against the connected database and returns a data table or scalar value containing the result.
Declaration
public static object EvaluateDax(string dax)
Parameters
Type | Name | Description |
---|---|---|
string | dax | The DAX expression to be evaluated |
Returns
Type | Description |
---|---|
object | A DataTable if the DAX expression returns a table value, otherwise a primitive type representing the scalar value of the evaluation. |
ExecuteCommand(string, bool)
Executes the specified TMSL or XMLA command.
Declaration
public static void ExecuteCommand(string tmslOrXmla, bool isXmla = false)
Parameters
Type | Name | Description |
---|---|---|
string | tmslOrXmla | A TMSL or XMLA string. |
bool | isXmla | Set to true if |
ExecuteDax(string)
Executes the specified DAX query.
Declaration
public static DataSet ExecuteDax(string dax)
Parameters
Type | Name | Description |
---|---|---|
string | dax | A DAX query which contains one or more EVALUATE statements. |
Returns
Type | Description |
---|---|
DataSet | A DataSet object which contains the resulting datasets from the query. |
ExecuteReader(string)
Executes the specified DAX query.
Declaration
public static IDataReader ExecuteReader(string dax)
Parameters
Type | Name | Description |
---|---|---|
string | dax | A DAX query which contains one or more EVALUATE statements. |
Returns
Type | Description |
---|---|
IDataReader | An IDataReader-object that allows you to iterate the results of the query. |
ExportProperties(IEnumerable<ITabularNamedObject>, string)
Export properties of the specified set of objects to a TSV (tab-separated) string. Use ImportProperties(string) to import properties from a TSV string.
Declaration
public static string ExportProperties(IEnumerable<ITabularNamedObject> objects, string properties = "Name,Description,SourceColumn,Expression,FormatString,DataType")
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<ITabularNamedObject> | objects | Set of objects whose properties should be serialized |
string | properties | (Optional) Comma-separated list of properties to export. If omitted, a default set of properties are exported. |
Returns
Type | Description |
---|---|
string |
FormatDax(IEnumerable<IDaxDependantObject>, bool?, bool?)
Format all DAX expressions on the specified objects.
Declaration
public static void FormatDax(IEnumerable<IDaxDependantObject> objects, bool? shortFormat = null, bool? skipSpaceAfterFunctionName = null)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<IDaxDependantObject> | objects | |
bool? | shortFormat | |
bool? | skipSpaceAfterFunctionName |
FormatDax(string, bool?, bool)
Format the specified DAX expression
Declaration
public static string FormatDax(string dax, bool? shortFormat = null, bool skipSpaceAfterFunctionName = false)
Parameters
Type | Name | Description |
---|---|---|
string | dax | |
bool? | shortFormat | |
bool | skipSpaceAfterFunctionName |
Returns
Type | Description |
---|---|
string |
FormatDax(IDaxDependantObject)
Flags the specified object for formatting after script execution or the next time CallDaxFormatter(bool?, bool?) is called.
Declaration
public static void FormatDax(IDaxDependantObject obj)
Parameters
Type | Name | Description |
---|---|---|
IDaxDependantObject | obj |
GetObjectPath(TabularObject)
Returns a string representation that uniquely identifies the specified object within the model.
Declaration
public static string GetObjectPath(TabularObject obj)
Parameters
Type | Name | Description |
---|---|---|
TabularObject | obj |
Returns
Type | Description |
---|---|
string |
ImportProperties(string)
Applies properties to objects based on a string representation (tab separated format) of property values to assign, such as obtained by ExportProperties(IEnumerable<ITabularNamedObject>, string).
Declaration
public static void ImportProperties(string tsvData)
Parameters
Type | Name | Description |
---|---|---|
string | tsvData | The tab separated property values to assign |
Info(string)
Displays an informational message in a popup dialog. When the script is running in the CLI, an information message is written to the console.
Declaration
public static void Info(string message)
Parameters
Type | Name | Description |
---|---|---|
string | message |
LineBreakFirstChar(string, bool)
Ensures that a DAX expression starts with a line break.
Declaration
public static string LineBreakFirstChar(string dax, bool onlyIfMultiline = true)
Parameters
Type | Name | Description |
---|---|---|
string | dax | The DAX expression |
bool | onlyIfMultiline | Set to true if the line break character should only be inserted when the DAX expression itself spans multiple lines. |
Returns
Type | Description |
---|---|
string |
Remarks
In Power BI Desktop, DAX expressions are shown on a formula bar with the name of the object prepended. For this reason, it is often useful to have a line break as the first character of the actual DAX expression.
Macro(IEnumerable<ITabularNamedObject>, int)
Run a macro on a selection of objects.
Declaration
public static void Macro(IEnumerable<ITabularNamedObject> selection, int macroId)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<ITabularNamedObject> | selection | The object selection on which the macro should run. |
int | macroId | Id of the macro |
Macro(IEnumerable<ITabularNamedObject>, string)
Run a macro on a selection of objects.
Declaration
public static void Macro(IEnumerable<ITabularNamedObject> selection, string macroName)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<ITabularNamedObject> | selection | The object selection on which the macro should run. |
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
Macro(int)
Run a macro.
Declaration
public static void Macro(int macroId)
Parameters
Type | Name | Description |
---|---|---|
int | macroId | Id of the macro |
Macro(string)
Run a macro.
Declaration
public static void Macro(string macroName)
Parameters
Type | Name | Description |
---|---|---|
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
Macro(ITabularNamedObject, int)
Run a macro on an object.
Declaration
public static void Macro(ITabularNamedObject selection, int macroId)
Parameters
Type | Name | Description |
---|---|---|
ITabularNamedObject | selection | The object on which the macro should be run. |
int | macroId | Id of the macro |
Macro(ITabularNamedObject, string)
Run a macro on an object.
Declaration
public static void Macro(ITabularNamedObject selection, string macroName)
Parameters
Type | Name | Description |
---|---|---|
ITabularNamedObject | selection | The object on which the macro should be run. |
string | macroName | Name of the macro. Use fully path of macro in case of ambiguity. |
Output(object)
Displays detailed information about the specified object or collection of objects in a popup dialog. When executed through the UI, the user has an option to ignore additional popups. When the script is running in the CLI, the information is written to the console.
Declaration
public static void Output(object value)
Parameters
Type | Name | Description |
---|---|---|
object | value | An object or collection of objects |
ReadFile(string)
Read the specified file as text
Declaration
public static string ReadFile(string filePath)
Parameters
Type | Name | Description |
---|---|---|
string | filePath |
Returns
Type | Description |
---|---|
string |
ResolveObjectPath(string)
Resolves an object within the model based on a string such as the one obtained by GetObjectPath(TabularObject).
Declaration
public static TabularObject ResolveObjectPath(string path)
Parameters
Type | Name | Description |
---|---|---|
string | path |
Returns
Type | Description |
---|---|
TabularObject |
SaveFile(string, string, Encoding)
Saves the specified text to a file
Declaration
public static void SaveFile(string filePath, string content, Encoding encoding = null)
Parameters
Type | Name | Description |
---|---|---|
string | filePath | Path of the file - file will be created if it does not already exist, and overwritten otherwise |
string | content | Content to write to the file |
Encoding | encoding | (Optional) Encoding to use |
SelectColumn(IEnumerable<Column>, Column, string)
Displays a dialog that allows the user to select a column from the specified list of columns.
Declaration
public static Column SelectColumn(IEnumerable<Column> columns, Column preselect = null, string label = "Select column:")
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<Column> | columns | A list of columns to be shown to the user |
Column | preselect | (Optional) A column from the list of columns, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Column | The selected column or null if the user cancels out of the dialog |
SelectColumn(Table, Column, string)
Displays a dialog that allows the user to select a column from the specified table.
Declaration
public static Column SelectColumn(Table table, Column preselect = null, string label = "Select column:")
Parameters
Type | Name | Description |
---|---|---|
Table | table | The table from which the user should select a column |
Column | preselect | (Optional) A column from the list of columns, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Column | The selected column or null if the user cancels out of the dialog |
SelectMeasure(IEnumerable<Measure>, Measure, string)
Displays a dialog that allows the user to select a measure from the specified list of measures.
Declaration
public static Measure SelectMeasure(IEnumerable<Measure> measures, Measure preselect = null, string label = "Select measure:")
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<Measure> | measures | A list of measures to be shown to the user |
Measure | preselect | (Optional) A measure from the list of measures, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Measure | The selected measure or null if the user cancels out of the dialog |
SelectMeasure(Measure, string)
Displays a dialog that allows the user to select a measure from the model.
Declaration
public static Measure SelectMeasure(Measure preselect = null, string label = "Select measure:")
Parameters
Type | Name | Description |
---|---|---|
Measure | preselect | (Optional) A measure from the model, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Measure | The selected measure or null if the user cancels out of the dialog |
SelectMeasure(Model, Measure, string)
Displays a dialog that allows the user to select a measure from the model.
Declaration
public static Measure SelectMeasure(Model model, Measure preselect = null, string label = "Select measure:")
Parameters
Type | Name | Description |
---|---|---|
Model | model | The model from which a measure should be selected by the user |
Measure | preselect | (Optional) A measure from the model, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Measure | The selected measure or null if the user cancels out of the dialog |
SelectMeasure(Table, Measure, string)
Displays a dialog that allows the user to select a measure from the specified table.
Declaration
public static Measure SelectMeasure(Table table, Measure preselect = null, string label = "Select measure:")
Parameters
Type | Name | Description |
---|---|---|
Table | table | A table containing the measures that will be shown to the user |
Measure | preselect | (Optional) A measure from the table, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Measure | The selected measure or null if the user cancels out of the dialog |
SelectObject<T>(IEnumerable<T>, T, string)
Displays a dialog that allows the user to select a model object from a list of objects.
Declaration
public static T SelectObject<T>(IEnumerable<T> objects, T preselect = null, string label = "Select object:") where T : TabularNamedObject
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<T> | objects | A list of objects to be shown to the user |
T | preselect | (Optional) An object from the list, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
T | The selected object or null if the user cancels out of the dialog |
Type Parameters
Name | Description |
---|---|
T | The type of objects shown to the user |
SelectObjects<T>(IEnumerable<T>, IEnumerable<T>, string)
Displays a dialog that allows the user to select one or more model objects from a list of objects.
Declaration
public static IList<T> SelectObjects<T>(IEnumerable<T> objects, IEnumerable<T> preselect = null, string label = "Select object(s):") where T : TabularNamedObject
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<T> | objects | A list of objects to be shown to the user |
IEnumerable<T> | preselect | (Optional) A list of objects which are preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
IList<T> | The selected object(s) or null if the user cancels out of the dialog |
Type Parameters
Name | Description |
---|---|
T | The type of objects shown to the user |
SelectTable(IEnumerable<Table>, Table, string)
Displays a dialog that allows the user to select a table from the specified list of tables.
Declaration
public static Table SelectTable(IEnumerable<Table> tables, Table preselect = null, string label = "Select table:")
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<Table> | tables | A list of tables to be shown to the user |
Table | preselect | (Optional) A table from the list of tables, which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Table | The selected table or null if the user cancels out of the dialog |
SelectTable(Model, Table, string)
Displays a dialog that allows the user to select a table from the model.
Declaration
public static Table SelectTable(Model model, Table preselect = null, string label = "Select table:")
Parameters
Type | Name | Description |
---|---|---|
Model | model | The model from which a table should be selected by the user |
Table | preselect | (Optional) A table which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Table | The selected table or null if the user cancels out of the dialog |
SelectTable(Table, string)
Displays a dialog that allows the user to select a table from the model.
Declaration
public static Table SelectTable(Table preselect = null, string label = "Select table:")
Parameters
Type | Name | Description |
---|---|---|
Table | preselect | (Optional) A table which is preselected when the dialog is shown |
string | label | (Optional) A label to be shown within the dialog |
Returns
Type | Description |
---|---|
Table | The selected table or null if the user cancels out of the dialog |
SuspendWaitForm(Action)
Hides the "Please wait" spinner while performing the specified action. Useful if the action displays custom dialogs / UI to the end user.
Declaration
public static void SuspendWaitForm(Action action)
Parameters
Type | Name | Description |
---|---|---|
Action | action |
Remarks
Built-in script UI such as the Info(string, int) and SelectMeasure(IEnumerable<Measure>, Measure, string) functionality will automatically hide the "Please wait" spinner.
SuspendWaitForm<T>(Func<T>)
Hides the "Please wait" spinner while performing the specified action. Useful if the action displays custom dialogs / UI to the end user.
Declaration
public static T SuspendWaitForm<T>(Func<T> action)
Parameters
Type | Name | Description |
---|---|---|
Func<T> | action |
Returns
Type | Description |
---|---|
T |
Type Parameters
Name | Description |
---|---|
T |
Remarks
Built-in script UI such as the Info(string, int) and SelectMeasure(IEnumerable<Measure>, Measure, string) functionality will automatically hide the "Please wait" spinner.
Warning(string)
Displays a warning message in a popup dialog. When the script is running in the CLI, a warning message is written to the console.
Declaration
public static void Warning(string message)
Parameters
Type | Name | Description |
---|---|---|
string | message |