Code Comments in BimlScript

Three Ways to Comment in BimlScript

BimlScript files are a mix of XML markup, code nuggets, and (sometimes) directives. Each layer has its own comment syntax, and choosing the right one matters because the wrong choice can leave executable code running where you expected it to be skipped. This walkthrough covers the three comment styles you will use in BimlScript and explains when each one is appropriate.

XML Comments

XML comments use the standard {/* ... */} syntax and are the most familiar option for anyone who has worked with HTML or XML.

There is one important caveat that catches new users: code nuggets inside an XML comment still execute. That behavior is intentional. Some authors deliberately wrap blocks of code in XML comments for debugging or documentation purposes, run a one-time expansion to capture the generated output, and then continue working. If you simply want to disable a code nugget, an XML comment will not do the job.

C# and VB Comments

Inside a code nugget, the standard C# and VB single-line and block comment syntax works exactly as you would expect:

• // comment for a single line in a C# nugget
• /* ... */ for a block comment in a C# nugget
• ' comment for a single line in a VB nugget

Use these when you want to disable individual statements or short blocks of logic inside a code nugget without removing the surrounding nugget delimiters.

BimlScript Comments

BimlScript also defines its own comment syntax, <#* ... *#>, which exists specifically to disable an entire range of BimlScript markup. Everything inside one of these blocks is ignored by the compiler, including XML, code nuggets, and directives.

Use this form when you want to comment out a region that contains a mix of Biml and embedded code without having to comment each layer separately. For example:

<#*
Comments: So what did this BimlScript code do?
We used C# code to automate the addition of Biml, and thus SSIS package generation.
We also introduced two types of control blocks;
the standard control block delimited by <# ... #> and
the expression control block delimited by <#= ... #>.
A standard control block is a nugget of program code that can control whether the Biml inside it is added to the Biml file, and thus sent to the Biml engine.
In the <# if(i%2==0) { #> ... <# } #> control block, the Biml is only added to the output when the if statement evaluates to true.
When it's false, the Biml is not added to the file.
BimlScript file also has an expression block; <#=i#>.
In this expression block, we get the integer value that's defined in the <# for(int i = 1; i <= 5; ++) { #> control block,
and insert it as part of the Biml text block. Notice that we did not have to convert the i variable to a string data type; BimlScript does this for us. The output of expression blocks is always a string data type.
*#>

The comment block above safely hides several lines of mixed prose and code-nugget syntax, none of which will be processed by the BimlScript compiler.

Choosing the Right Comment Style

Use case	Recommended syntax
Add notes around Biml elements you still want to render	{/* ... */}
Disable a few lines of code inside a single nugget	// or /* ... */ (C#) / ' (VB)
Disable a region containing Biml, nuggets, or directives	<#* ... *#>