Basic BimlScript Structure


Paul S. Waters

The basic elements of a BimlScript file are covered.

published 09.13.12

last updated 09.14.12



  • Assemblies
  • Directive

A BimlScript file contains the Biml that will be generated from it. Included in a BimlScript file are control blocks, which are fragments of program code; sometimes referred to as code nuggets. Control blocks allow for parts of the Biml to be repeated and conditional.

An easy way to start creating a BimlScript file is to first create a Biml file that produces your desired results and then make it into a BimlScript file by adding control blocks.

BimlScript files are composed of the following parts:
Directives - elements that control how the template is processed.
Text blocks - content that is copied directly to the output.
Control blocks - program code that inserts variable values into the text, and controls conditional or repeated parts of the text.


BimlScript directives instruct the Biml engine and compiler on how to interpret the BimlScript file. For example, the following template directive instructs the Biml compiler to interpret the code inside the control blocks as C# and compile it in the 3rd tier so that output from tiers 0, 1, and 2 can be available for the BimlScript to use. `<#@ template language="C#" tier="3"#>

Text Blocks

A text block is the general term for text that inserts directly into the output. A text block can be more narrowly defined based on the type of text contained in it. For example a text block with Biml in it is referred to as a Biml block, and one with SQL as a SQL block. This is a subtle, but important distinction, since some BimlScript editors can offer features such as auto complete for Biml blocks and not SQL or general text blocks.

Control Blocks

Control blocks are sections of code, sometime referred to as code nuggets that are used to control the output of the text blocks. The default language for control blocks is C#, but Visual Basic can be used by adding the following directive at the beginning of the file: `<#@ template language="VB" #>

Standard Control Blocks

A standard code block is a section of C# or VB code that that generates parts of the outputted Biml. Each standard control block is delimited by the symbols <# ... #>. You can have as many control blocks and text blocks you need to create you solution in a BimlScript file. However, you cannot place one control block inside of another.

Expression Code Block

Expression code blocks evaluate an expression and then convert it to a string in the Biml output. Expression control blocks are delimited by the symbols <#= ... #>
The expression can include any variable that is in scope. For example, this BimlScript creates five empty packages.

<Biml xmlns="">
    for(int i = 1; i < 6; i++)
	<Package Name="Package<#=i#>" ConstraintMode="Linear" />

Using External References Assemblies Every BimlScript file has the follow default assemblies referenced:
• System.dll
• System.Core.dll
• System.Data.dll
• System.Xml.dll
• System.Xml.Linq.dll
• WindowsBase.dll

BIDS Helper also has:
• BimlEngine.dll

Varigence Mist also has:
• Biml.dll
• FlowFramework.dll
• HadronExtensions.dll
• HadronCoreLowerer.dll

In addition to the default assemblies you can reference other .Net assemblies or your own custom assemblies. Assemblies can be reference by either a path name, or the strong name of the assembly.

Including code and text

The include directive inserts text from another Biml or text file. For example, this directive inserts the content of iVariables.biml. `<#@ include file="C:\Dev\Samples\Getting Started With BimlScript\iVariables.biml" #>

Think of the included text as if the text in the include file were copied and pasted where the include directive is located. The include file can be referenced by absolute or relative paths, and environment variables can be used as part of an absolute path. The file attribute value is evaluated in the following order:
1. Expand environment variables, if there are any.
2. Check if the result from #1 is a file that exists – absolute path
3. Check if it is a relative path to the current/referencing file.
4. Check if it is a relative path to BimlEngine.dll (i.e. BIDS Helper installation directory).

You are not authorized to comment. A verification email has been sent to your email address. Please verify your account.




10:49am 09.22.14

It doesn't seem to be possible to reference an assembly of my own creation via anything other than a hard path. For instance I tried using VS macro's in the same way that T4 templates use them and I found (via procmon) that the BIML engine doesn't resolve them. For example...

<#@ assembly name="$(ProjectDir)myCode.dll" #>

procmon showed that the BIML engine was looking for a file called $(ProjectDir)myCode.dll

Is it possible to have a dynamic reference? Having hard coded paths is simply not a viable option.



12:17pm 01.11.16

Hi Gary, I just resolved this issue using an environment variable in the assembly path, e.g. <#@ assembly name= "%Path%\HelloWorld.dll" #>



9:37pm 01.06.17

I have a fresh install of VS2015 and Bimlexpress 1.0 I have walked through this setup and everything seems to work as expected, until I click box of the biml files and generate the ssis packages, it asks for me to confirm to over write the files and then I get object reference is not set to an instance of an object. thoughts?