Getting Started with BimlScript - Part 3

gravatar

Paul S. Waters

Part 3: Familiarizes the reader with BimlScript directives, which are used to control how BimlScripts are processed. The walkthrough also shows how template tiers let a Biml author control the order in which BimlScript files are processed.

published 09.10.12

last updated 05.20.13


Share

Previous walkthrough in the Getting Started with BimlScript series: Getting Started with BimlScript - Part 2

In this walkthrough, we’ll learn about BimlScript directives, template processing tier groups, and the Biml API. To demonstrate these, we are going to create a BimlScript template that automatically generates a package that executes the five packages created in the Getting Started with BimlScript - Part 2 walkthrough.

BimlScript directives provide instructions to the Biml engine on how to process a BimlScript template. In this walkthrough, we are going to learn about the template directive. Note that in the previous walkthrough, the BimlScript file didn’t have a directive. This is because the default template directive was used. The default template directive is:

<#@ template language="C#" tier="1" #>

This directive instructs the BimlEngine to interpret the code in the control blocks as C# code, and process the template in the tier 1 processing group. If you would like to use Visual Basic.NET, instead of C#, then set language="VB" in the template directive. The tier attribute comes into play when you want to combine the execution of BimlScript files that are dependent on the output of other BimlScript files. To accomplish this, template processing tier groups are required.

Template processing groups guarantee that all the output from templates in tier 1 will be compiled before templates in tier 2, and tier 2 will be compiled before tier 3, and so on. In other words, tier n is always compiled before tier n+1. The power of tiers is that tier n+1 can apply Biml APIs to the compiled output of tier n.

Let’s try using a tier:

  1. Open the Getting Started with BimlScript project.
  2. Right click on the SSIS Packages folder inside Solution Explorer. Then click Add New Biml File in the context menu.
  3. Rename the added file to My Package Driver.biml.
  4. Double click My Package Driver.biml to open it.
  5. In the editor, add a line above the <Biml xmlns="http://schemas.varigence.com/biml.xsd"> tag and type the following directive:
    <#@ template language="C#" tier="2" #>
  6. Next, add the following Biml between the Biml tags:
<Packages>  
    <Package Name="My Package Driver" ConstraintMode="Linear" AutoCreateConfigurationsType="None">
        <Tasks>
  1. Under the tasks tag, add the following code nugget to loop through the packages created in the My Packages.biml file :
    <# foreach (var package in RootNode.Packages) { #>
  2. Then, add the following Biml block:
  
<ExecutePackage Name="Run <#=package.Name#>">  
    <Package PackageName="<#=package.Name#>" />  
</ExecutePackage>
  1. Close the foreach loop by typing the following on the next line:
    <# } #>
  2. Finally, type the following to close the open Biml elements:
       </Tasks>
    </Package>
</Packages>

Your My Package Driver.biml file should match the following:

<#@ template language="C#" tier="2" #>
<Biml xmlns="http://schemas.varigence.com/biml.xsd">
	<Packages>
		<Package Name="My Package Driver" ConstraintMode="Linear" AutoCreateConfigurationsType="None">
			<Tasks>
				<# foreach (var package in RootNode.Packages) { #>
				<ExecutePackage Name="Run <#=package.Name#>">
					<Package PackageName="<#=package.Name#>" />
				</ExecutePackage>
				<# } #>
			</Tasks>
		</Package>
	</Packages>
</Biml>

With these changes in place, try generating the SSIS packages for this Biml:

  1. Right-click My Package Driver.biml and click Generate SSIS Packages.

When you do, you will see the Biml Validation Items dialog box displaying one error regarding the Tasks element. The gist of this message is that a Tasks element needs 1 or more task elements inside of it.

Inside the Tasks element, we have a control block that loops through RootNode.Packages, and a Biml block with the Execute Package task. Since the Biml engine did not find any packages in RootNode.Packages, a validation error was thrown since the Tasks collection is empty. So, where do we obtain packages to add to RootNode.Packages? The answer is from our My Packages.biml file.

Let’s retry generating a package from My Package Driver.biml file, but this time doing the following:

  1. Press and hold the <Ctrl> key.
  2. Click My Package Driver.biml
  3. Click My Packages.biml and release the key.
  4. Right-click either of the selected files and click Generate SSIS Packages.
  5. The Confirm Overwritten Items dialog box will appear. Click Commit to overwrite the current SSIS packages with the new ones.
  6. Open the new My Package Driver.dtsx package to see what was generated.

By including My Packages.biml and My Package Driver.biml when generating assets, the Biml engine followed a different procedure:

  1. Both of the BimlScript files were sent to Biml engine to be compiled.
  2. The files were evaluated and the execution order was determined by the value of the tier attribute in each file’s template directive.
  3. The My Packages.biml file was compiled first and added to an in-memory Biml model.
  4. Next, the My Package Driver.biml file was compiled and the compiler used the in-memory model to evaluate and compile the BimlScript.

By compiling My Packages.biml first, its packages were added to the RootNode’s Packages collection. Thus, the Biml engine was able to loop through the RootNode’s package elements when compiling the My Package Driver.biml file. As a result, our desired My Package Driver.dtsx package was generated.

In this walkthrough, we used a template directive to assign a BimlScript to a tier group, along with learning how template tier groups are processed. We also began using the Biml API by iterating the RootNode.Packages collection.

To learn more about the structure of a BimlScript file, please read Basic BimlScript Structure.

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

Comments

gravatar

Paul6

12:59pm 10.31.12

Is it possible that I missed some setup tasks? All the directives are underlined with the red squiggle, the following line '<#@ template="" language="C#" tier="2" #> has the error message "Illegal Syntax Expecting valid start name character" It does generate the packages though

gravatar

Paul S. Waters

3:48pm 04.29.13

Paul6

This has to do with how VS handles pasted text when it thinks it is getting valid XML. Please see the http://bimlscript.com/Walkthrough/Details/45 walk through to learn how to remedy this.

Thanks.

Paul

gravatar

Zsombor

8:31am 01.30.15

Hi Paul W.

I have the same problem as Paul6. I made the settings you recommend on the page but the problem persists. It is not about the copy/paste, I wrote the code myself. The problem is that apparently these <#@ are not interpreted correctly by the syntax highlighter and the BIML parser. I could send a screenshot but I have no possibility to upload here.

Thanks.

gravatar

Adrian Chacon

10:14pm 03.04.15

Awesome Tutorial! I only got a taste of SSIS development but I already know how many headaches I'll save by implementing BIML. copy+paste code causes too many problems... might be a better idea to just type it all out...

gravatar

john6

9:55pm 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?

gravatar

L

3:35pm 01.13.17

John6, did you ever figure this out? I have the exact same issue, VS2015 along with that Error.

gravatar

Pavel6

10:22am 07.18.17

I have the same issue as john6. Please, can someone explain to me what is a problem? Thanks. Pavel