Skip to main content

Getting Started with BimlScript - Part 3

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 <Ctrl> 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.