Of course the company can only be as great as the people working there make it. I would like to thank these great people working at Microsoft for the inspiration and support: Joe Healy, Gareth Jones, Jim Blizzard, Jean-Mark Prieur, Jeff Barnes, Scott Hanselman, Rob Caron, Tim Fischer. Regardless of whether "community work" is in your job description or not, you helped me in one way or another and I am grateful for that.

This award also would not be possible without the prominent members of the Microsoft community: Scott Doorman, Stan Schultes, Dave Noderer, John Dunagan, Steve Lane, Shawn Weisfeld, Roy Lawson and many many more. So much goes on behind the scenes to keep the user groups going and prepare the code camps. Without your work the development community in Florida wouldn’t be as great as it is today.

And last, but not least, I want to thank my friends and colleagues at Catapult: Jeff Odell, Randy Patterson, Terri Burmeister, James McAuliffe. Whether it was buying pizza for a user group meeting, discussing technical issues after hours or having a beer after work, your encouragement and support is very much appreciated.

Sincerely,
Oleg

©2009 Oleg Sych. All Rights Reserved.

You will need latest versions of the following tools installed in order to compile T4 Toolbox.

• Visual Studio 2008 Professional or Team edition
• StyleCop
• WiX 3.0
• Visual J# 2.0 Redistributable Package
• SDC Tasks

Installing Tools

You can install most of the tools with default options.

• When installing StyleCop, make sure that MSBuild integration files feature is installed.

• SDC Tasks don’t have an installer; binary files come in a ZIP archive. For T4 Toolbox, you will need to extract these files to C:\Windows\Microsoft.NET\Framework\v3.5 directory.

• Open the extracted Microsoft.Sdc.Common.tasks XML file and comment out the <PropertyGroup/> element in the beginning of the file (enclose it with <!– and –>). This element generates warnings during compilation.
• Unless you have BizTalk installed on your workstation, you will also need to comment out the entire section at the bottom of this file that declares BizTalk tasks implemented in Microsoft.Sdc.Tasks.BizTalk.dll assembly. Otherwise you will see a large number of errors referring to BizTalk assemblies during compilation.

Accessing Source Code

You have two different ways of getting T4 Toolbox source code. If you have not been added to the list of developers,

• On the Source Code tab of the project page, click a Download link for the latest check-in.

• After accepting the license agreement, you will be prompted to download a ZIP archive that contains the latest version of the T4 Toolbox source code. Save the file to your local hard drive first and unblock it before extracting the files. Unless you unblock the ZIP archive first, the Visual Studio will not “trust” it and you will get obscure security errors and warnings later on.

• Extract all files from this archive to a folder on your hard drive, such as C:\T4Toolbox, and open T4Toolbox.sln located in the Source subfolder.

• When Visual Studio opens T4 Toolbox solution for the first time, select the Load project normally option. T4Toolbox.csproj uses MSBuild extensions from SDC tasks and StyleCop, you will need to select this option in order to compile it.

At this point, you should be able to compile the T4 toolbox. Make changes until it works the way you need it and then upload the files you modified as a patch on CodePlex. Myself or someone else will take a look at the changes you’ve made and commit them to the main source code of the project.

Using Team Explorer

When you are regularly working on T4 Toolbox source code, having to download a source code snapshot becomes a hassle. When your CodePlex account has been added to the list of T4 Toolbox developers, you can start using Team Explorer from Visual Studio.

• Download and install Team Explorer from here.
• Once you have it installed, go to T4 Toolbox page on CodePlex, make sure you are logged (1), open the Source Code tab (2) and then click the Visual Studio Team Explorer link (3). On the right-hand side, you will see the information you will need to use in Team Explorer (4).

• In Visual Studio, select View->Team Explorer from the main menu.
• In Team Explorer, click Add Existing Team Project button
• In the Connect to Team Foundation Server dialog, click Servers button
• In the Add/Remove Team Foundation Server dialog, click Add button
• In the Add Team Foundation Server dialog, enter server name, port number and protocol from the CodePlex page and click OK.

• Back in the Add/Remove Team Foundation Server dialog, click Close button
• Back in the Connect to Team Foundation Server dialog, select T4Toolbox project and click OK button
• Back in Team Explorer, you should now see the T4Toolbox project and its information.

• Double-click the Source Control node to open Source Control Explorer

• In Source Control Explorer, select T4Toolbox folder on the left side and click the Not mapped link on the right.
• In the Map dialog, enter name of the local folder you want to use for T4 Toolbox source code and click Map button.

• Back in Source Control Explorer, click Get Latest Version  button to download the source code to your local hard drive.
• Once downloaded, double-click T4Toolbox.sln in the Source sub-folder to open the solution.

At this point, you can check files out, change them and check them in. The source control functionality is similar to Visual SourceSafe and Subversion, so it should be familiar to most developers.

©2009 Oleg Sych. All Rights Reserved.

This limitation of the built-in LINQ to SQL functionality is one of the reasons developers start using a second tool, such as SQL Server Database Diagrams, Visio for Enterprise Architects or Enterprise Architect by Sparx Systems, and designing the database schema separately from the application model. While this approach works, it significantly increases complexity of the development process. Every change now needs to be made in two places - the database model and the application model. In all but trivial cases, making these changes by hand is too tedious and error-prone to be practical. You are better off choosing one model and somehow synchronizing it with the other. Today, developers typically choose database model as the source of truth and update the entity model based on it, or in other words, use database-driven or database-first approach.

LINQ to SQL includes two tools that allow you to generate .dbml from an existing database - O/R Designer and SqlMetal.exe . Unfortunately, both of these tools overwrite existing dbml and don’t allow you to preserve customizations made in the raw relational model imported from the database. SqlMetal also allows you to generate application code from a database directly. By choosing these tools, you are limiting your LINQ to SQL model to a direct representation of your relational database schema and eliminate the possibility of taking advantage of the object-oriented features the framework supports, such as inheritance of entity classes, member access and virtual member modifiers. Alternatively, you can use these tools to create the initial version of the entity model you will customize later, however that brings you back to the issue of maintaining two models separately.

There are third-party tools that make ongoing database-driven development of LINQ to SQL applications more practical. In particular, PLINQO, a set of code generation templates developed by CodeSmith, includes a sophisticated model synchronization logic, which updates .dbml based on database schema while attempting to preserve the customizations. However, these tools don’t eliminate the fundamental requirement of maintaining the two models separately. By itself, this requirement is not a problem. On a large-scale project with a complex database schema, this may well be a necessity. However, on a small- to medium-scale project, having to maintain the two models separately is often an additional, unnecessary burden.

Build 9.5 of T4 Toolbox extends the LINQ to SQL generator introduced in version 9.1 with support for database schema generation. This gives you the ability to generate both application code, such as entity and data context classes, and database code, such as table, primary and foreign key scripts, from a single LINQ to SQL dbml file in your solution. Generated database scripts can be automatically added to a VSTS Database project, which will automatically handle majority of database deployment issues by automatically generating the ALTER scripts. In other words, combined with VSTS Database edition, T4 Toolbox  allows you to use model-driven or model-first approach for ongoing development of LINQ to SQL applications.

Usage

• Download and install the latest version of T4 Toolbox from CodePlex.
• In Visual Studio, create a new or open an existing C# project and select Project->Add New Item in the main menu.
• In the Add New Item dialog, select Code Generation->LINQ to SQL model

• Enter the name you want to use for the new LINQ to SQL model (.dbml) file. Note that this name also determines name of the DataContext class that will be generated (OrderEntryDataContext will be generated for OrderEntry.dbml). Click the Add button when finished.

Just like with the previous version of this template, you will see that two files, a .dbml and a .tt, were added to your project. This time, instead of populating the entity model by dragging and dropping tables from the Server Explorer to the O/R Designer, take a couple of minutes to create the model from scratch and take advantage of some of the LINQ to SQL features like inheritance and associations. There is no need to enter mapping information, such as table or column names and database types. The generator will automatically deduce them from the type names, property names and CLR types respectively.

Alternatively, you can download the sample source code accompanying this article. The sample includes an entity model of a simplistic Order Entry application shown above. This model showcases some of the features supported by the code generator, including auto-generated properties (Contact.Id), version properties (Contact.RowVersion), derived types (Employee, Customer, Vendor) , associations (Contact_Employee) and associations where a derived type serves as a parent (Customer_Order).

• Add a new VSTS database project to the solution.

Make sure to select an appropriate project type in the Database Projects  folder of the Add New Project dialog. Legacy database project template, located under Other Project Types -> Database will not work. If you don’t have Database edition of VSTS installed, you can use any C# project type instead.

• In the previously created .tt file (OrderEntry.tt in this example), modify the code to assign DatabaseProject property of the LinqToSqlGenerator instance.

<#@ template language="C#v3.5" hostspecific="True" debug="True" #>
<#@ output extension="log" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="T4Toolbox\LinqToSql.tt" #>
<#
    // Generate entity classes from a LINQ to SQL class model (.dbml file)
    LinqToSqlGenerator generator = new LinqToSqlGenerator();
    generator.DbmlFile = "OrderEntry.dbml";
    generator.DatabaseProject = @"..\Database\Database.dbproj";
    generator.Run();
#>

DatabaseProject value is a path to the database project file, relative to the location of the .tt file. When you save the .tt file, it will generate table, primary and foreign key scripts in this project. At this point, you can build the VSTS Database project and deploy the OrderEntry database to a SQL server. Detailed discussion of the VSTS Database project functionality is outside of scope this article, suffice it to say that this should require only right-clicking the database project in Solution Explorer and selecting Deploy from the context menu.

As you continue using O/R designer to add new properties and types to the LINQ to SQL model, simply right-click the OrderEntry.tt file in the Solution Explorer and select Run Custom Tool to regenerate the database code, build the database project, deploy and let VSTS automatically apply ALTER scripts to the existing database.

Feature Highlights

Let’s review some the features supported by this code generator.

CREATE TABLE dbo.Contact
(
    Id INT NOT NULL IDENTITY,
    Type tinyint,
    RowVersion ROWVERSION,
    FirstName NVARCHAR(4000),
    LastName NVARCHAR(4000),
    StreetAddress NVARCHAR(4000),
    City NVARCHAR(4000),
    State NVARCHAR(4000),
    Zip NVARCHAR(4000),
    Phone NVARCHAR(4000),
    Email NVARCHAR(4000),
    SocialSecurityNumber NVARCHAR(4000),
    EmergencyContactId INT,
    AccountNumber NVARCHAR(4000),
    CreditCardNumber NVARCHAR(4000),
    CreditCardExpiration NVARCHAR(4000)
);

Derived types mapped to base table

The generator automatically generates columns for derived types, such as Employee, in the table of their base type, such as Contact. In particular, SocialSecurityNumber is a property of the Employee type, stored in the Contact table.

IDENTITY columns

The generator automatically maps integer properties with Auto Generated Value attribute set to true, such as Id,  to IDENTITY columns.

ROWVERSION data type

The generator automatically maps byte[] and Binary properties with Time Stamp attribute set to true, such as RowVersion, to the ROWVERSION data type.

Enum columns

The generator automatically maps enum properties, such as Type property of the Contact class, to SQL data type INT. You can also specify the server data type explicitly. In the application, the property will be generated with the original enum type.

private ContactType type;

[Column(Name = "Type", /* … */ DbType = "tinyint")]
public ContactType Type { /* … */ }

This allows you to write strongly-typed queries like so:

var dc = new OrderEntryDataContext(Settings.Default.Database);
var employees = from c in dc.Contacts
                where c.Type == ContactType.Employee
                select c;

Primary keys

ALTER TABLE dbo.Contact
    ADD CONSTRAINT PK_Contact
    PRIMARY KEY CLUSTERED (Id);

The generator automatically produces a primary key script for properties with Primary Key attribute set to true.

Delimited Identifiers

CREATE TABLE dbo.[Order]
(
    Id INT NOT NULL IDENTITY,
    OrderDate DATETIME NOT NULL,
    EmployeeId INT NOT NULL,
    ProductId INT NOT NULL,
    RowVersion ROWVERSION,
    CustomerId INT NOT NULL,
    Price DECIMAL(29,4) NOT NULL,
    PONumber NVARCHAR(4000)
);

The generator automatically uses delimited identifiers to avoid errors when original identifier is a reserved SQL keyword, such as Order, or contains spaces, such as Order  Details. Otherwise, the generator uses the original, un-delimited identifiers to improve readability.

Foreign Keys

ALTER TABLE dbo.[Order]
    ADD CONSTRAINT FK_Customer_Order
    FOREIGN KEY (CustomerId)
    REFERENCES dbo.Contact (Id);

The generator automatically produces foreign key scripts for associations. Note that in case of Customer_Order association, the parent type Customer is actually derived from Contact. The foreign key correctly references the base table, however the generated association property (shown below), is of the derived type, Customer.

[Association(Name = "Customer_Order", /* … */ IsForeignKey = true)]
public Customer Customer { /* … */ }

Sample Source Code

Sample source code, available for download below, includes a solution with three projects - Model, Database and Application. Model is a C# class library project that contains OrderEntry.dbml (LINQ to SQL model) and OrderEntry.tt (code generator). Entity and Data Context classes are generated in the Model project, while SQL scripts are generated in the Database project. Note that this project requires VSTS Database edition. Application is a C# console application that creates a sample database on the local SQL Server instance, populates it with sample data and executes several queries.

Closing Thoughts

The new version of LINQ to SQL generator in T4 Toolbox allows you to use model-first approach for ongoing developing database applications.

So what’s the big deal? Simplicity.

• There is no need to use a separate modeling tool when developing a database application. You can generate both database and application code without leaving Visual Studio IDE.
• There is only one diagram to maintain, which reflects both entity and database models. If you are editing both at the same time, there is no way you can forget update one of them after updating the other.
• There is only one step in the code generation process - Run Custom Tool from Solution Explorer. You don’t need to remember to make the changes in the modeling tool, export the schema, build the schema, synchronize the .dbml file with the schema and finally generate the application code from .dbml.

What’s the catch then? Limited scalability and flexibility.

• O/R designer is limited to a single diagram, which puts practical limitations on the number of tables you can manage with this approach.
• What you can generate is limited by what you can model in the O/R designer - tables, primary keys and foreign keys. (INSERT, UPDATE and DELETE procedures can also be generated, this is under development now).
• Entity and database models are closely related and cannot be developed separately. If you have an existing database, you may not be able to use this approach.

Will it work for you? It depends.

This approach will work best on greenfield projects with a small- to medium-size database and teams who prefer implementing business logic in application code, not stored procedures and triggers. You can certainly optimize time-critical logic by selectively implementing it stored procedures and exposing them in the LINQ to SQL model. However, you will be swimming against the current if you want to rely on the stored procedures extensively. On brownfield projects, this approach will work as well if you have a database of appropriate size and can limit database modifications to the O/R Designer. This approach will not work well if you have a database with hundreds of tables and/or multiple database developers actively creating tables and stored procedures.

Download

• T4 Toolbox
• Sample source code

©2009 Oleg Sych. All Rights Reserved.

As a consultant, I feel obligated to advise my clients on using integrated Windows authentication as the most secure authentication mechanism for their networks and custom solutions. Unfortunately, as a consultant, I also need to access my clients’ networks from my Catapult laptop, across domain boundaries. This is where integrated Windows authentication makes my job more difficult. Typically, I cannot use my Catapult domain credentials to access resources on the client’s domain and have to supply an alternative set of Windows credentials explicitly. Some applications, like Internet Explorer and Visual Studio are smart enough to prompt you to enter Windows credentials when necessary. While these applications may prompt you to enter credentials more often than you might like, other applications don’t prompt you at all and simply fail. In particular, database applications connecting to SQL Server will not prompt for credentials and display the infamous “Cannot establish SSPI context” error when you try use them across domain boundaries.

Thankfully, there is a relatively small number of tricks you need to use to get most applications using integrated Windows authentication work successfully across domain boundaries. These tricks are described below, but before you rush to try them, make sure you have configured name resolution and can successfully connect to a network resource on the target domain using it’s name. Windows authentication will not work without successful name resolution.

Stored user names and passwords

Windows allows you to store login credentials for various authentication mechanisms, including Windows or Active Directory credentials. You can store a single Windows login (CLIENT\account) and password for an entire domain (*.client.lan) and Windows will use these credentials automatically whenever you access any computer on it.

Not all types of applications support stored user names and passwords. HTTP applications, such as Internet Explorer, Team Foundation Explorer in Visual Studio, and other applications using WebClient, are one of them. Whenever you type http://target.client.lan in Internet Explorer, the WebClient will send the matching stored credentials to the target computer automatically, without prompting you. Windows Explorer, Performance Monitor, Event Viewer and other applications relying on network shares also support this mechanism. As long as you have credentials stored, these applications will just work, as if your computer was a member of the target domain. Here is how you set it up.

• Open User Accounts from Control Panel and click the Manage your network passwords link on the left.

• If you are using an older version of Windows, such as XP or 2003 Server, you will need to click the Manage Passwords button on the Advanced tab of the User Accounts dialog.

• In the Stored User Names and Passwords dialog you need to click the Add button and create a credential entry for the target domain you need to access. Assuming that one of the computers you need to access has a fully-qualified domain name target.client.lan, you want to store credentials for a wildcard *.client.lan, which will used when you access any computers on that domain.

You can find more information about storing user names and passwords in the Microsoft knowledge base article 281660.

Internet security zone

As an added security measure, Internet Explorer will send your current or stored credentials to the target host only when it believes to be a member of the Intranet zone. It will assume that any host addressed with a fully-qualified domain name such as target.client.lan is on the public internet and will not send the credentials automatically. This protects your identity from being stolen by a rouge web site getting your Windows credentials without your permission.

As you can see from the snapshot of Internet Explorer security settings below, even adding the target host to the list of trusted web sites will not work.

In order for Windows authentication to work automatically across domain boundaries, without you having to type in your credentials for every page, you will need to add a particular host or its entire domain to the Local Intranet zone.

• Select Internet Options in Control Panel
• On the Security tab of the Internet Properties dialog, select Local intranet icon and click Sites button
• In the Local intranet dialog, click Advanced button

• In the second Local intranet dialog, enter URL of the web site and click Add button.

Just like with stored user names and passwords, you can use wildcards that apply to all computers on the target domain. For example, if you enter http://*.client.lan, Internet Explorer will consider target.client.lan and all other computers on the client.lan domain to be in the Local intranet zone and send stored user names and passwords to them automatically.

WebClient configuration

Unfortunately, Microsoft Office applications will continue prompting you to enter credentials when accessing files stored on a SharePoint site even after you add the target domain to the Local intranet zone. You will need to modify WebClient configuration in registry to prevent this from happening.

• Open HKLM\System\CurrentControlSet\Services\WebClient\Parameters key in Registry Editor.

• Double-click the AuthForwardServerList value
• In the Edit Multi-String dialog, enter the target URL on a separate line and click OK.

This setting also supports wildcards. If you enter http://*.client.lan, Microsoft Office applications will automatically send stored Windows credentials to any SharePoint you access on the client.lan domain. You can learn more about this in Microsoft knowledge base article 941050.

Runas /netonly

Some applications don’t support stored user names and passwords. For example SQL Server Management Studio will not be able to connect to a database on a different domain using Windows authentication. In these cases you can use the runas command with netonly option and make the application access network resources under a different set of credentials.

c:\>runas /user:CLIENT\account /netonly ssms.exe
Enter the password for CLIENT\account:
Attempting to start ssms.exe as user "CLIENT\account" ...

When started with the command line above, SQL Server Management Studio will use CLIENT\account to connect to all SQL servers instead of the actual account you used to log into your computer (CATAPULT\osych in my case). In other words, if you need to connect to a database on sqlserver.client.lan, it will use CLIENT\account credentials you supply.

This trick works for all applications that need to connect to SQL Server using integrated windows authentication, not just SQL Server Management Studio. You can use it to run Visual Studio (devenv.exe) and your custom applications.

You can also use the ShellRunas utility to provide netonly credentials interactively. Once you downloaded and saved the utility in a permanent location on your hard drive, you will need to register it like so.

c:\Program Files (x86)\SysInternals>ShellRunas /reg /quiet  

c:\Program Files (x86)\SysInternals>ShellRunas /regnetonly /quiet

The registration adds Run as different user and Run as different user (netonly) menu items to the shell (i.e. Explorer) context menus for executables.

You can start Visual Studio with netonly context by right-clicking it in the Start menu and selecting the option. Simply provide the credentials required by the target computer you want to access on the other domain and click OK.

While you can also run an application completely under another account, not just netonly, this will only work if the domain you are trying to access has a trust relationship with your own domain. Even then, running an application completely under another account is less convenient than netonly because it runs in a different user profile, loosing your settings, shortcuts and favorites. Remember to select netonly option as it is easy to accidentally omit it.

Local accounts

If none of the options described above works, your last resort is local accounts and workgroup authentication. In workgroup mode, when there is no Active Directory domain controller, i.e. no centralized authentication authority, Windows relies on having matching local accounts on all computers in a workgroup. For example, an application running under local Administrator on your computer, let’s say it’s called CATLAPTOP, can access computer called TARGET on another domain under its local Administrator account as long as CATLAPTOP\Administrator and TARGET\Administrator accounts have the same passwords on both computers. This works for any account, not just Administrator, subject to permissions assigned to the local account on the target computer.

Using local accounts and workgroup authentication appears to be the recommended approach for some advanced cross-domain networking scenarios, such as remote debugging and SQL Server integrated security. However, these particular scenarios work with runas/netonly approach as well. Unlike the workgroup authentication approach, runas/netonly doesn’t require you to get access to a local account on each target computer. Maintaining these accounts is a hassle for IS administrators and they are typically reluctant to do it. You will probably want to use this option only as a last resort.

If you have to use this option, make sure that your local security policy allows workgroup authentication.

• Select Local Security Policy from Control Panel under Administrative Tools
• In the Local Security Policy console, find Security Options under Local Policies

• Make sure that the Network access: Sharing and security model for local accounts option is set to Classic - local users authenticate as themselves.

Conclusion

Relying on integrated Windows authentication and Active Directory for centralized authentication is a great way to make information systems in your organization more secure. While making life of users and administrators easier by allowing them to use and manage a single set of login credentials for various network resources and applications, integrated Windows authentication presents an additional barrier when you need to access network resources across domain boundaries. Luckily a relatively small set of configuration changes can help you solve most of these difficulties.

This article describes configuration changes and utilities in the order from easiest and most commonly used to most difficult and infrequently used. You will probably want to store credentials for the new domain and add it to the Local intranet security zone first. This enables most modern applications to access network resources on the target domain without errors and without bothering you with constant prompts for credentials. If you need to access Microsoft Office documents on a SharePoint site, you may also want to configure WebClient to automatically use your stored credentials instead of prompting you every time. For advanced scenarios, such as database applications and remote debugging, use the runas command with netonly option or its interactive equivalent, ShellRunas. If all other options fail, you may have to resort to using local accounts and workgroup authentication.

Name resolution and authentication are not the only problems you have to solve to access network resources. Advanced scenarios may require you to make changes in firewall, group policy, security policy, registry and file configurations a particular application may be affected by. Discussion of these scenarios is outside of scope of this article. You can usually find specific instructions in Microsoft knowledge base.

©2009 Oleg Sych. All Rights Reserved.

Assuming that you already connected to the client’s network with the help of DHCP, your first challenge is to get name resolution working. Name resolution is a process that converts human readable host names into numeric addresses used by TCP/IP. Whenever computer program uses a network address, such as a web URL http://target, the host name has to be converted or resolved to an IP address before the target host can be accessed over the network from your computer. When both your computer and the target host are on the same domain, this process works seamlessly. However, when computer and the target host are on different domains, you may need to make additional configuration changes.

There are two name resolution mechanisms in active use today: NetBIOS and DNS. Although both of these these protocols were developed in the early 1980s, NetBIOS was implemented on the Windows platform first and then has fallen out of favor with release of Windows 2000 and Active Directory, which provided support for DNS.

C:\>ipconfig /all

Windows IP Configuration

   Host Name . . . . . . . . . . . . : CATTAMLAPTOP
   Primary Dns Suffix  . . . . . . . : catapultsystems.com
   Node Type . . . . . . . . . . . . : Hybrid
   IP Routing Enabled. . . . . . . . : No
   WINS Proxy Enabled. . . . . . . . : No
   DNS Suffix Search List. . . . . . : catapultsystems.com
                                       dmz.catapultsystems.com

Ethernet adapter Local Area Connection:

   Connection-specific DNS Suffix  . : client.lan
   Description . . . . . . . . . . . : Broadcom NetXtreme 57xx Controller
   Physical Address. . . . . . . . . : 00-11-22-33-44-55
   DHCP Enabled. . . . . . . . . . . : Yes
   Autoconfiguration Enabled . . . . : Yes
   Link-local IPv6 Address . . . . . : fe80::3424:f17e:93ec:8912%11(Preferred)
   IPv4 Address. . . . . . . . . . . : 172.16.242.13(Preferred)
   Subnet Mask . . . . . . . . . . . : 255.255.0.0
   Lease Obtained. . . . . . . . . . : Thursday, April 23, 2009 4:12:45 PM
   Lease Expires . . . . . . . . . . : Thursday, April 30, 2009 4:12:45 PM
   Default Gateway . . . . . . . . . : 172.16.1.2
   DHCP Server . . . . . . . . . . . : 10.10.4.22
   DNS Servers . . . . . . . . . . . : 10.10.4.6
                                       10.10.4.8
   NetBIOS over Tcpip. . . . . . . . : Enabled

You can tell which mechanism is available by looking at the output produced by ipconfig command. In particular, the DNS Servers setting will tell you if a DNS server is available for name resolution and NetBIOS over Tcpip setting will tell you if NetBIOS is enabled.

Name resolution through DNS

DNS works in client-server mode, where your computer sends a name resolution request to a DNS server and the server sends back the IP address registered for the specified host name. To use DNS for name resolution, first you need to use the ipconfig command (shown above) to verify that a DNS server is available. Typically, this will be configured automatically, by DHCP, when your computer connects to the network.

Because the Domain Name System is hierarchical, DNS server cannot uniquely resolve a local name such as target. Before sending a host name to the server, DNS client will try to guess its fully-qualified domain name (FQDN), such as target.client.lan, based on the list of known DNS suffixes it has access to through various configuration settings. It will keep asking the configured DNS servers to resolve the potential names until it finds a match. The order of DNS servers and domain suffixes is important because the DNS client will use the first one it can resolve. If it happens to be a wrong guess, you will not be able to connect to the desired target host.

Primary DNS suffix

The primary DNS suffix a suffix of the fully-qualified domain name of your computer. As you can see in the Windows IP Configuration section of the ipconfig output below, the primary DNS suffix on my laptop is catapultsystems.com.

C:\>ipconfig /all

Windows IP Configuration

   Host Name . . . . . . . . . . . . : CATTAMLAPTOP
   Primary Dns Suffix  . . . . . . . : catapultsystems.com
   Node Type . . . . . . . . . . . . : Hybrid
   IP Routing Enabled. . . . . . . . : No
   WINS Proxy Enabled. . . . . . . . : No
   DNS Suffix Search List. . . . . . : catapultsystems.com
                                       dmz.catapultsystems.com

DNS client configuration

The Windows IP Configuration section of the output of ipconfig command also shows you the search list of suffixes specified in the DNS client configuration. By default, the DNS Suffix Search List will include only domain suffixes for your own domain. You can change this list using Registry Editor as shown below.

Also keep in mind that your domain administrator may be controlling this and other DNS client settings using Active Directory group policy.

Network adapter configuration

TCP/IP settings of your network adapter configuration can also provide DNS suffixes for name resolution. As you can see on the screenshot below, you can either specify a connection-specific suffix or an entire list of different DNS suffixes and their order.

Configuring and verifying DNS name resolution

As we discussed, DNS client will try to resolve a local host name such as target, by appending the list of domain suffixes it knows about and sending them to the DNS server until it finds a fully-qualified domain name the server can resolve. Unfortunately, this process is complicated by having two different sources of this information on your computer (DNS client configuration and network adapter configuration), different implementations of DNS servers and network administrators controlling these settings through group policy. I had better luck with DNS client configuration and prefer to use it exclusively. However, I can imagine a different combination of these conditions where network adapter configuration may work better.

In our example, where we need to access a host called target located on the Active Directory domain client.lan, use the Registry Editor to add client.lan to beginning of the comma-delimited search list of DNS suffixes. You could also use a registry import file similar to one show below, just make sure you replace the Catapult domain suffixes with your own.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\DNSClient]
"SearchList"="client.lan,catapultsystems.com,dmz.catapultsystems.com"

Once you have configured the list of domain suffixes, verify that your DNS client can resolve target host name using ping and nslookup commands as shown below.

C:\>ping target

Pinging target.client.lan [10.10.4.74] with 32 bytes of data:
Reply from 10.10.4.74: bytes=32 time=2ms TTL=127
Reply from 10.10.4.74: bytes=32 time=1ms TTL=127
Reply from 10.10.4.74: bytes=32 time=1ms TTL=127
Reply from 10.10.4.74: bytes=32 time=1ms TTL=127

Ping statistics for 10.10.4.74:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 1ms, Maximum = 2ms, Average = 1ms

C:\>nslookup target
Server:  dns.client.lan
Address:  10.10.4.6

Name:    target.client.lan
Address:  10.10.4.74

The nslookup command will tell you if the DNS server is available, if it can resolve the host name and what the local host name was actually resolved to. This step is important to verify that your DNS client guessed the fully-qualified domain name of the target host correctly. Depending on configuration, the DNS client may try using the primary DNS suffix first and ask the server to resolve target.catapultsystems.com before it asks about target.client.lan. Some DNS servers I had to connect to in the past would happily accept these names from other domains and return incorrect IP addresses.

The ping command will tell you if the actual target host is available. Typically computers will respond to ping requests within a local network, but keep in mind that some network administrators may turn this service off to improve security and reduce network traffic.

On rare occasions, the DNS client may not be able to resolve the target host name immediately after you change the configuration. In  this case, you can can give it a nudge by flushing DNS cache and pinging the target host again.

C:\>ipconfig /flushdns

Windows IP Configuration

Successfully flushed the DNS Resolver Cache.

Name resolution through NetBIOS

With Windows 2000, DNS replaced WINS as a recommended name resolution mechanism. NetBIOS can work in two modes - peer-to-peer, when name resolution requests are broadcast across the local network, and client-server, when name resolution requests are sent to a NetBIOS Name Service, also known as WINS. Although many company no longer have WINS servers on their network, you may still be able to use it in peer-to-peer mode. Whether it works will depend on the target host being within the reach for name resolution broadcasts from your computer and having the NetBIOS setting enabled. NetBIOS also works great for name resolution in small home network and virtual networks between several VMs on a single physical host.

In order to use NetBIOS successfully, check the adapter configuration section of the ipconfig output to see whether NetBIOS over Tcpip is Enabled on both your computer and the target host.

C:\>ipconfig /all

Ethernet adapter Local Area Connection:

   Connection-specific DNS Suffix  . : client.lan
   Description . . . . . . . . . . . : Broadcom NetXtreme 57xx Controller
   Physical Address. . . . . . . . . : 00-11-22-33-44-55
   DHCP Enabled. . . . . . . . . . . : Yes
   Autoconfiguration Enabled . . . . : Yes
   Link-local IPv6 Address . . . . . : fe80::3424:f17e:93ec:8912%11(Preferred)
   IPv4 Address. . . . . . . . . . . : 172.16.242.13(Preferred)
   Subnet Mask . . . . . . . . . . . : 255.255.0.0
   Lease Obtained. . . . . . . . . . : Thursday, April 23, 2009 4:12:45 PM
   Lease Expires . . . . . . . . . . : Thursday, April 30, 2009 4:12:45 PM
   Default Gateway . . . . . . . . . : 172.16.1.2
   DHCP Server . . . . . . . . . . . : 10.10.4.22
   DNS Servers . . . . . . . . . . . : 10.10.4.6
                                       10.10.4.8
   NetBIOS over Tcpip. . . . . . . . : Enabled

You can change this setting in network adapter configuration as shown below. Note that Default setting for NetBIOS may mean both enabled or disabled. You may want to set it explicitly if you need to use NetBIOS.

Having verified that NetBIOS over TCP/IP is enabled, you can use ping and nbtstat commands to verify if you can resolve name of the target host through NetBIOS.

C:\>ping target

Pinging target [172.16.1.195] with 32 bytes of data:
Reply from 172.16.1.195: bytes=32 time=1ms TTL=128
Reply from 172.16.1.195: bytes=32 time=2ms TTL=128
Reply from 172.16.1.195: bytes=32 time=7ms TTL=128
Reply from 172.16.1.195: bytes=32 time=2ms TTL=128

Ping statistics for 172.16.1.195:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 1ms, Maximum = 7ms, Average = 3ms

C:\>nbtstat -r

    NetBIOS Names Resolution and Registration Statistics
    ----------------------------------------------------

    Resolved By Broadcast     = 1
    Resolved By Name Server   = 0

    Registered By Broadcast   = 3
    Registered By Name Server = 0

    NetBIOS Names Resolved By Broadcast
---------------------------------------------
           TARGET       <00>

nbtstat will confirm if target host name was resolved through NetBIOS broadcast and ping will confirm if the target host can be reached via TCP/IP. Notice that even though the target host is a member of an Active Directory domain, both ping and nbtstat commands report only its local name. This may be important if the application you are trying to reach on the target host was configured to use fully-qualified domain names.

Conclusion

In order to access network resources on a different Active Directory domain, you often need to make additional configuration changes to allow name resolution process to work correctly. Although it is possible to use fully-qualified domain names, such as target.client.lan, or even raw IP addresses, such as 172.16.1.195, many applications are configured to use local host names and will not work correctly. In particular, an application, such as Windows SharePoint Services, may have the local host name embedded in its configuration and will encounter errors after initial successful connection.

In my experience, using DNS-based name resolution and adding the target DNS suffix (client.lan) to the DNS client search list in registry works best. I found DNS client configuration to be more reliable than changing TCP/IP settings of the network adapter. I’ve had situations where DNS suffixes configured through TCP/IP settings would not work no matter what I tried. However, you may have to use network adapter TCP/IP settings if the DNS client configuration is controlled by the Active Directory group policy in your organization.

Although outmoded by DNS in Active Directory networks, NetBIOS-based name resolution is still useful when working on small networks that don’t have Active Directory, such as a home networks or a virtual networks built using Virtual PC and Loopback Adapter. Make sure that NetBIOS over TCP/IP is enabled to take advantage of this name resolution mechanism.

What’s next

Once you have name resolution working correctly, your next challenge when accessing network resources is authentication. Majority of applications on the Microsoft platform rely on integrated Windows authentication to allow administrators to manage security in company’s Active Directory. Integrated Windows authentication is a great improvement compared to custom authentication and authorization mechanisms that were prevalent in applications before. Unfortunately, it also creates additional difficulties when you try to access network resources and applications across domain boundaries. In some cases, these difficulties are seemingly insurmountable and lack of knowledge forces us to fall back on older, custom authentication mechanisms, such as SQL Server authentication. However, solutions exist for most of these problems, which is the topic of the next article (coming soon).

©2009 Oleg Sych. All Rights Reserved.

While developing enterprise applications, development teams commonly face a challenge of ongoing development of new features and maintenance of the version already released to production. Consider a team that implements a new feature in April. The new feature goes through testing and gets released to production. The team begins working on the next new feature and starts actively changing code. Then in May, a serious bug is reported by users in production environment. The development team needs to make a hot fix but there is not enough time and not enough resources to put the hot fix through a full test cycle. How can the team make sure that the problem is fixed production without all the changes that were made to implement the new feature for next major version?

A proven approach to solving this problem is to take the snapshot of the source code that was used to compile the version of the application currently in production; make the changes required to fix the problem in this snapshot; build a new version that only contains the bug fixes; concentrate on testing the bug fixes; limit amount of the overall system testing based on available resources and impact of the changes; deploy the hot-fix build to production.

Extensive guidance exists on how to support this scenario using source control functionality in Team Foundation Server. In particular, Team Development with Visual Studio Team Foundation Server (TFS Guide) provides a comprehensive list of strategies in Chapter 5. TFS 2008 Branching Guide is a more recent set of specific guidelines, consistent with Chapter 5 of the TFS Guide. Here is a set of scenarios TFS Guide defines.

• Scenario 1 – No Branches. Your team works only from the main source tree. In this case, you do not create branches and you do not need isolation. This scenario is generally for small or medium size teams that do not require isolation for teams or for features, and do not need the isolation for releases.
• Scenario 2 – Branch for Release. Your team creates branches to support an ongoing release. This is the next most common case where you need to create a branch to stabilize for a release. In this case, your team creates a branch before release time to stabilize the release and then merges changes from the release branch back into the main source tree after the software is released.
• Scenario 3 – Branch for Maintenance. Your team creates a branch to maintain an old build. In this case, you create a branch for your maintenance efforts, so that you do not destabilize your current production builds. You may or may not merge changes from the maintenance branch back into the main tree. For example, you might work on a quick fix for a subset of customers that you do not want to include in the main build.
• Scenario 4 – Branch for Feature. Your team creates branches based on features. In this case, you create a development branch, perform work in the development branch, and then merge back into your main source tree. You can create separate branches for work on specific features to be completed in parallel.
• Scenario 5 – Branch for Team. You branch to isolate sub-teams so they can work without being subject to breaking changes, or can work in parallel towards unique milestones.

These scenarios provide solid advice that will scale to largest teams and projects. However, we need to keep in mind that there is an immediate overhead associated with multiple branches in the form of the initial learning curve every team member needs to go through as well as ongoing effort required to merge between branches. On a small team where developers work on one project at a time and projects have medium cycle durations (measured in a few months), the need to release hot fixes may arise only occasionally. In scenarios like this, branching approach may be an overkill, causing more problems than it solves. An alternative approach can be used to achieve the goal of releasing a hot fix without having to resort to branching and merging.

Solution

With Team Foundation Server, we can rely on workspaces to obtain the isolation required to work with a snapshot of the released source code. The idea is to get a labeled snapshot of source code of the production build; make the changes required to fix the problem; check in the modified files; apply a hot-fix label to the files in the workspace; and make Team Build get and build the hot fix version instead of latest. Let’s take a look at these steps in more detail.

Get source code released to production

Assuming that development team is already using Team Build, here is how one could get a snapshot of the production source code from source control.

• In Source Control Explorer, right click root folder of the team project and select Get Specific Version from the context menu.
• In the Get dialog, select Label as Version Type and click the […] button to find the label of the build that was released to production.

• In the Find Label dialog, select the name of your project in the Project drop-down list and click Find.

• Select the appropriate label in the Results list and click Close button. If you have a large number of builds, you may need to limit the scope of search by owner and label name.
• Back in the Get dialog, click Get button. Visual Studio will download a snapshot of the code that was compiled by Team Build and released to production.

Make changes required to fix the problem

• Before you open your solution, make sure that you don’t have “Get everything when a solution or project is opened” setting turned on.

Having downloaded the snapshot of production source code in your workspace, you can now modify it to fix the production problem. You will need to check in the changes you made in order to make them available for Team Build. Note that any changes you check in apply to both current and released version.

In addition to fixing the problem itself, you will also need to modify the Team Build definition. Normally, Team Build will automatically generate a new build number based on the current date. You will need to modify the Team Build definition file to allow overriding build number using MSBuild command-line parameters.

• Add the following XML to the build definition file. Build definition files are typically called TFSBuild.proj and located in the $/<ProjectName>/TeamBuildTypes/<BuildName> directory of your project in source control.

<!– Define property to override default build number  –>
<PropertyGroup>
    <OverrideBuildNumber></OverrideBuildNumber>
</PropertyGroup>

<!– Override automatically generated build number –>
<Target Name="BuildNumberOverrideTarget"
        Condition="‘$(OverrideBuildNumber)’ != ”">
    <CreateProperty Value="$(OverrideBuildNumber)">
        <Output TaskParameter="Value" PropertyName="BuildNumber" />
    </CreateProperty>
</Target>

Note this fragment defines a custom MSBuild property, OverrideBuildNumber, we will later use to specify the specific hot fix version of source code Team Build needs to compile. It also overrides a standard BuildNumberOverrideTarget defined by Team Build to override the automatically generated, standard BuildNumber property when OverrideBuildNumber is specified.

Although exact placement of the PropertyGroup and Target elements within the parent Project element inside of TFSBuild.proj shouldn’t matter, it is a good idea to place the OverrideBuildNumber property close to other properties in the beginning of the file, and the Target element close to other tasks in the end of the file. MSBuild files follow the traditional interface/implementation source file layout.

Apply label to identify the hot fix version of source code

Normally, Team Build will automatically get the latest version of source code for each build and label it once the build is completed. However, to build a snapshot of the production source code with the hot fix applied, we will need to label it in our workspace first. Team Build will then use this label to download it from source control.

• Right-click the project root in the Solution Explorer and select Apply Label from the context menu
• In the Choose Item Version dialog, select “Workspace Version” and click OK.

• In the Apply Label dialog, enter name of the hot fix label and click OK.

Name of the hot fix label will be typically based on the label of the last production build. In this example, the last production build was labeled as FirstBuild_20090414.1, so we use FirstBuild_20090414.2 for the hot-fix build. Although in your case, the numbering scheme may be different, the general idea of incrementing the revision portion of the build number should still apply.

Make Team Build get and build the hot fix version

• Right-click the build in Team Explorer and select Queue New Build item from the context menu.
• In the Queue Build dialog, use the “MSBuild command-line arguments” text box to specify values for GetVersion and OverrideBuildNumber properties.

GetVersion is a standard property that specifies which version Team Build needs to pull from source control for the build. It’s value matches format of the VersionSpec parameter of the tf get command. In this example, it needs to be LLabelName, where (first) L is a required prefix and LabelName is the name of the hot fix label we applied previously. OverrideBuildNumber is the custom property we defined in our TFSBuild.proj.

• Click the Queue button.

Unless there were some error made in TFSBuild.proj or the source code, the build should complete successfully.

Results

The sample source code accompanying this article illustrates the Workspace approach. It reflects the following scenario.

• On April 14, development team delivers a build labeled FirstBuild_20090414.1 to QA team for testing.
• On April 15, development team begins actively working on features for the next major version.
• On April 28, after a 2 week testing cycle QA team releases build 20090414.1 to production.
• On May 14, a developer checked in implementation of a new feature, scheduled for the next major release.
• On May 14, development team delivers a build labeled FirstBuild_20090515.1 of the new major version to QA team for testing.
• On May  21, a critical production bug was identified.
• On May 21, development team fixes the production problem and delivers a hot fix build labeled FirstBuild_20090414.2 to the QA team for testing.
• On May 22, After a 4  hour testing cycle QA team releases hot fix 20090414.2 to production.
• On May 22, development team resumes working on the new version and delivers new build labeled FirstBuild_20090522.2 to the QA team for testing.

Change History

Note the changeset numbers shown below.

Changeset 220 contains changes for the next major version. In particular, it contains Form1.Designer.cs file, where a new Label was added. Change 221 contains changes required for the hot fix. It contains a modified version of Form1.cs.

Build History

Note that the hot fix build 20090414.2 was done after a new feature changes was checked in on 5/14 in changeset 220.

Below you can see what got built in the hot fix build 20090414.2. Although Form1.Designer.cs was modified on 5/14 to implement new features, note that this build contains the original version of this file (changeset 218) and new version of Form1.cs (changeset 221), which was modified for the hot fix.

And here is what got built in the next regular build 20090522.1 of the new version on May 22. Note that it contains new versions of both Form1.Designer.cs (changeset 220) modified earlier and Form1.cs (changeset 221) modified for the hot fix. In other words, changes made for the hot fix were immediately applied to the main codebase of the next major version of the application.

Finally, below are the contents of the drop directory. As you can see the drop directory for build 20090414.2 was successfully created on 5/22 when the build was performed.

Conclusion

Approach described in this article allows to create a hot-fix for a Team Foundation build created in the past without introducing untested side effects and without branching the source code. This approach relies on a TFS workspace to provide temporary isolation of the source code required to apply the hot fix. Because this isolation is temporary, the workspace approach will not work for more complex scenarios, such as when a file where hot fix needs to be made is already modified in the new version or has been renamed. On the other hand, in simple scenarios, where ongoing parallel maintenance of the production version is not necessary, this approach offers a simpler solution that doesn’t impose added complexity of branching and merging on the development team.

The workspace approach can also be combined with the branching approach. The workspace approach could be used to release the initial hot-fix build. The development team can then switch to the branching approach when necessary. In this case, development team would branch the source code based on the label of the last hot-fix build.

Coincidentally, having the OverrideBuildNumber property in your Team Build script also gives you ability to recreate any previous build, not just a special hot-fix build. Imagine going through a long test cycle just to find out that a build you were about to deploy to production was accidentally deleted. Of course, having this ability in your Team Build script is not a substitute for a proper backup procedure. You may not be able to recreate the exact same build output if the Team Build script itself or the Build Server has changed since then.

Download

• Source code

©2009 Oleg Sych. All Rights Reserved.

Although Visual Studio 2008 includes T4, a fully-featured, template-based code generation engine, its support for editing of the code generation templates is very limited. Out of the box, code generation files appear and behave as regular text files in the Visual Studio editor. Not only does this means that you don’t have IntelliSense we have come to take for granted in the last 10 years, you also don’t have the color syntax highlighting which became a standard feature in IDEs 20 years ago. The lack of color syntax highlighting makes working with code generation templates particularly difficult because code blocks and text blocks blend together and make it hard to distinguish code that will be executed during code generation from the code that will be generated.

In order to take full advantage of the productivity offered by T4 and template-based code generation, you really need to have a modern design-time support in your IDE. Enter the T4 Editor by Tangible Engineering.

T4 Editor Features

Tangible T4 Editor extends the Visual Studio editor to provide color syntax highlighting and IntelliSense for T4 code generation files. There are too many features to describe in a blog post, but here are some of my favorites.

Color syntax highlighting

The color palette is very close to ASP.NET. A nice improvement is a subtle yellow background for code blocks that  helps you distinguish template code from the generated code. You get colors in both code blocks (based on the language specified in template directive) and text blocks (based on extension specified in output directive).

IntelliPrompt for T4 directives and code blocks

As soon as you type <, the editor displays a list of T4 directives and code blocks, helping you type them. If you select or type <#@, the editor will display a list of standard T4 directives. Once you select the directive, the editor displays prompts for each parameter, helping you along each step of the way.

IntelliPrompt and IntelliSense for template code

When editing template code in code blocks, the editor displays list of class members for a variable as soon as you type period. Once you select a particular method, the editor will display a hint with method signature. Placing text caret on an opening curly brace highlights it and its closing counterpart with green back color, helping you to locate it across text blocks that may be between them.

Support for included T4 files

The editor also provides IntelliSense for included T4 files. Pointing cursor at the DatabaseProject of the LinqToSqlGenerator class included via LinqToSql.tt displays the documentation comments! This is extremely helpful when working with T4 Toolbox templates that use included files extensively.

Conclusion

There is a lot more to the Tangible T4 Editor than would be practical to describe here. I have focused only on those features that help me in my daily work and intentionally left out the UML modeling tools Tangible provides together with the T4 Editor. These modeling tools can be used for building custom code generators as well.

If you are working with T4, I would definitely recommend for you to check it out. The guys at Tangible Engineering work hard to make their T4 Editor compatible with the T4 Toolbox and support complex, composite code generators.

The editor comes in two editions - free and professional. The free edition limits the IntelliSense to a small subset of core .NET assemblies. This version would be appropriate for developer primarily using the T4 code generators created by others. The professional version provides IntelliSense for all assemblies referenced by a T4 code generator and enables strongly typed access to the models created by Tangible modeling tools. Developers who routinely customize or create new T4 code generators will benefit from the additional productivity features offered by the professional edition.

Links

• T4 Editor: http://t4-editor.tangible-engineering.com
• Tangible Engineering: http://www.tangible-engineering.com

©2009 Oleg Sych. All Rights Reserved.

The problem is now fixed in the new version 9.3.21.2 of the T4 Toolbox. Special thanks to Daniel Fortunov, Rohan Cragg and stebrennan for reporting and helping to troubleshoot the error.

©2009 Oleg Sych. All Rights Reserved.

To accomplish this task in a T4 code generator today, we would have to place a separate T4 file in each folder where one or more output files need to be generated. This approach may be feasible, however it increases the number of code generation files you need to maintain and leads to errors when developers forget to regenerate one of many files after changing the model it uses. In addition to this, not all types of projects in Visual Studio currently support T4. Most notably, Database projects of VSTS Development edition don’t support custom tools and thus don’t allow using T4. It would be ideal to have a single T4 code generation file per model that creates all required output files in various folders and projects. However, this approach presents several major challenges.

Automation model for newer types of Visual Studio projects is implemented in .NET and cannot be accessed from T4 code running in templating AppDomain directly. Instead, the T4 code generator has to pass information about output files, their locations and target projects to the main AppDomain of Visual Studio and execute the code that updates Visual Studio solution and projects there.

Managing a set of output files saved in different folders and different projects also becomes more difficult. In order to automatically remove previously generated output files that are no longer necessary, we store the list of all generated files in the Visual Studio project that contains the T4 file. The generated files are stored as “DependentUpon” the T4 file that generated them and appear as nested items under the T4 file in the Solution Explorer. This approach doesn’t work for files in other folders because Visual Studio project model doesn’t support nested items in different folders or nested links. Instead, the T4 code generator has to store the list of generated output files in a separate file.

Detailed discussion of these problems and available solutions is outside of scope of this article and probably outside of reader’s interest. Version 9.3.21.1 of T4 Toolbox provides support for generating output files in different folders and different projects of Visual Studio solution. Complete details can be found in the source code on CodePlex.

Usage

• Download and install the latest version of T4 Toolbox from CodePlex.
• Create a Visual Studio solution with two C# Class Library projects - ClassLibrary1.csproj and ClassLibrary2.csproj.
• Add a new code generation file called CodeGenerator.tt to the first class library project.
• Modify contents of the new file to look like so:

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#
    SampleTemplate template = new SampleTemplate();
    template.Output.File = @"SubFolder\SampleOutput.txt";
    template.Output.Project = @"..\ClassLibrary2\ClassLibrary2.csproj";
    template.Render();
#>
<#+
    public class SampleTemplate : Template
    {
        protected override void RenderCore()
        {
            this.WriteLine("Hello, World!");
        }
    }
#>

• Notice that a new output file called SampleOutput.txt was generated in a folder called SubFolder of the second class library project, ClassLibrary2.csproj.
• Also notice that a log file, CodeGenerator.tt.log was generated under CodeGenerator.tt. This file contains a list of all output files produced by last successful transformation and looks like so:

// <autogenerated>
//   This file contains the list of files generated by CodeGenerator.tt.
//   ...
// </autogenerated>
..\ClassLibrary2\SubFolder\SampleOutput.txt
.\CodeGenerator.tt.log

Analysis

The first thing we need to review is the new Output property of the Template base class. It gets an object of type OutputInfo which defines the output file that will be produced by the template. OutputInfo currently has three properties - File, Project and Encoding.

OutputInfo.Project

This property is of type String. You can set this property to specify the Visual Studio project where output file will be generated. Its value can be a relative path, in which case T4 Toolbox will resolve it based on the location of the TemplateFile being transformed, CodeGenerator.tt in the example above. The target project must be loaded in the current Visual Studio solution, or an error will be reported. By default, Project property is empty, which is interpreted as “the project that contains the TemplateFile being transformed” (ClassLibrary1 in the example above).

OutputInfo.File

This property is of type String. You can set this property to specify the file where output of the template will be stored. Its value can be a relative path, in which case T4 Toolbox will resolve it based on the location of the target project (see OutputInfo.Project above). By default, File property is empty, which means “standard output file of the TemplateFile being transformed” (CodeGenerator.txt in the example above). If File property contains only a file name without directory, the output file will be added as a nested project item under the main template file (CodeGenerator.tt in the example above).

OutputInfo.Encoding

This property is of type Encoding. You can set this property to specify encoding of the output file the template will produce. This is an equivalent of the encoding parameter of standard output directive provided by T4 which works for individual output files.

Template.Render()

Behavior of the Template.Render method now depends on the Output properties. By default, when Output.Project and Output.File are empty, Render adds output of the template to the standard output file, like it did in the previous versions of the toolbox.

Template.RenderToFile()

RenderToFile method has now become a convenience shortcut that sets Output.File and calls Render in a single statement.

Code generation log

Code generation log (CodeGenerator.tt.log) is created when at least one output file is generated in a different folder or a different project than the main TemplateFile. If all output files are generated in the same folder and the same project as the main TemplateFile, the list of generated output files is stored as a set of project items nested under it, like it did in the previous version.

Your feedback

Special thanks go to Jeff Odell, George Capnias and Billy McCaferty who provided their feedback on early versions of this functionality. Its design and implementation are based primarily on usage scenarios in the T4 Toolbox itself. It was a challenging process, requiring several tradeoffs. There is no feasible way for us to conduct usability studies, so your feedback will be very important in validating these decisions. Please give the new version a try and share your experience with us:

• Is the code easy to write?
• Does the code work as you would expect?
• Is the code intuitive?

Here are some design aspects we need your feedback on.

Template.Output property

Template.Output.File started as a simple Template.OutputFile property of type String. OutputInfo class and Template.Output property was created when we realized that there will be multiple attributes that will apply an output file. We felt that adding these additional attributes as properties to the Template class would pollute its interface and make concrete Template classes more difficult to use. As a result, we now have Output property which gets an object and have to write assignment statements with two periods in a chain just to assign output file or output project.

Relative Path Resolution

Relative path to Output.Project is resolved based on the location of the main TemplateFile. However, relative path to Output.File is resolved based on the location of the Output.Project. Initially, both paths were resolved relative to the location of the main TemplateFile. This feels logical and intuitive in a simple example where you have just one template. However, in a scenario with a complex directory structure and multiple templates such when generating SQL schema files in a VSTS Database project, the folder structure defined by Output.File doesn’t need to change based on Output.Project. In this case, it felt redundant having to write extra code for each Output.File in addition to simply changing Output.Project.

Code generation log

The initial goal was to continue storing the list of generated output files as nested items in the project that contains the main TemplateFile. Unfortunately, it appears to be impossible in the current Visual Studio project model to store links to files in other locations as nested project items under the main TemplateFile. The second choice was to store the log in standard output file of the main template and avoid having to create an extra file. However, Visual Studio overwrites the standard output file when there is a compilation error in the main template, which would obliterate your code generation log if you forget a semicolon at the end of the line and could result in dozens of orphaned output files in your solution. This is why we create code generation log as a separate file. Can you think of a better way to do this?

Download

• T4 Toolbox version 9.3.21.1

©2009 Oleg Sych. All Rights Reserved.

Introduction

When different developers or teams use the same code generator on different projects, it is likely that they will want to generate code differently. Consider the CRUD stored procedure generator we created previously. Here is a DELETE stored procedure it generates for Orders table in the Northwind sample database.

create procedure Orders_Delete
    @OrderID int
as
    delete from Orders
    where
        OrderID = @OrderID

Note that this T-SQL code will successfully create the stored procedure if it doesn’t exist. However, it will fail if the stored procedure has already been created. In order to handle both scenarios, we would need to change this code to look like this.

if  exists (select * from sys.objects
            where object_id = object_id(‘Orders_Delete’)
              and type in (‘P’, ‘PC’))
    drop procedure Orders_Delete
go 

create procedure Orders_Delete
    @OrderID int
as
    delete from Orders
    where
        OrderID = @OrderID

Although the new T-SQL file will handle both scenarios, the extra code it now contains is not necessary if you are using Database edition of Visual Studio Team System. The Database edition automatically generates different deployment scripts depending on the current schema in the target database. This additional code would only add extra code and complexity to the database project, making it not only unnecessary but undesirable.

Let’s assume that author of the original generator of CRUD stored procedures was targeting the Database edition of Visual Studio and did not implement code that drops existing procedures. How would a developer who doesn’t have the Database edition add this capability to the code generator?

It is always possible to simply modify code of the original generator to make it work the exact way you need it. However, by modifying the code someone else produced, you are taking on the responsibility of maintaining it. If you need to use a newer version of the original generator, you will have to re-implement your customizations in the new version of its code. For small code generators or short-term projects, this may be a valid approach. However, modifying complex code generators in a long-term project may significantly increase the effort required to maintain it over time. Luckily, we can use proven object-oriented design techniques such as inheritance and encapsulation to allow customizing code generators without resorting to hacking their source code.

Using virtual methods to make templates extensible

Here is an abbreviated version of template that generates delete stored procedure in the original CRUD generator.

<#+
public class DeleteProcedureTemplate : Template
{
    public string DatabaseName;
    public string TableName; 

    protected override void RenderCore()
    {
        // …
#>
create procedure <#= this.TableName #>_Delete
<#+
        // …
#>
as
    delete from <#= this.TableName #>
    where
<#+
        // …
    }
}
#>

Notice that RenderCore method is virtual. We can change its behavior by creating a descendant class and overriding the method like so:

<#+
class MyDeleteProcedureTemplate: DeleteProcedureTemplate
{
    protected override void RenderCore()
    {
#>
if  exists (select * from sys.objects
            where object_id = object_id(’<#= this.TableName #>_Delete’)
              and type in (’P', ‘PC’))
    drop procedure <#= this.TableName #>_Delete
go
<#+
        base.RenderCore();
    }
}
#>

Now we only need to replace the original template before running the CRUD generator in NorthwindProcedures.tt.

<#
    CrudProcedureGenerator generator = new CrudProcedureGenerator();
    generator.DeleteTemplate = new MyDeleteProcedureTemplate();
    generator.DatabaseName = “Northwind”;
    generator.Run();
#>

In other words, we have changed behavior of a third-party code generator defined in CrudProcedureGenerator.tt and DeleteProcedureTemplate.tt without directly modifying the third-party source code. All of our customizations are made in NorthwindProcedures.tt, which is a source file in our project. When new version of the CRUD generator becomes available, we can simply replace the older source files and our customizations will continue to work.

We can repeat these steps to override behavior of the InsertProcedureTemplate and UpdateProcedureTemplate. Completed working source code is available for download at the bottom of this article.

Conclusion

The customization described in this article was made possible by two important aspects of our CRUD generator design. First, generation of each type of stored procedures is encapsulated in a separate Template class with a virtual RenderCore method we could override. Second,  the generator class exposed templates as public fields, allowing us to replace individual templates without having to modify or override the generator. This design is a form of Strategy pattern, with template classes serving as Strategies and generator playing the role of Context.

In simple scenarios, when a single Template generates a single logical unit of code, such as a stored procedure, it is sufficient to simply place the code generation logic inside of the overridden RenderCore method. In more complex scenarios, a Template may generate multiple units of code, such as a C# class with multiple methods and properties. To allow users to customize generation of a particular unit of code without having to reimplement the entire RenderCore, consider creating a separate virtual method to generate each logical unit of code and calling it from the RenderCore method. This approach helps authors to reduce the size and complexity of the RenderCore method and also allows the users to override these virtual methods individually. This design is a form of Template Method pattern, with RenderCore serving as Template Method.

In the next article in the tutorial series, we will review some of the additional features the T4 Toolbox framework provides for code generator extensibility, such as conditional code generation and output redirection.

Download

• Source code, initial
• Source code, completed

©2009 Oleg Sych. All Rights Reserved.