{"id":1883,"date":"2009-03-19T19:28:00","date_gmt":"2009-03-19T19:28:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/2009\/03\/19\/new-tlbimp-release-on-codeplex-full-customization-of-interop-assemblies\/"},"modified":"2021-10-04T15:44:47","modified_gmt":"2021-10-04T22:44:47","slug":"new-tlbimp-release-on-codeplex-full-customization-of-interop-assemblies","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/new-tlbimp-release-on-codeplex-full-customization-of-interop-assemblies\/","title":{"rendered":"New TlbImp Release on CodePlex – Full Customization of Interop Assemblies"},"content":{"rendered":"

It has been a few months since our last release of TlbImp on CodePlex. We recently released a new version of TlbImp \u2013 please visit the <\/FONT>Codeplex<\/FONT><\/A> page for this tool to find out more. <\/FONT><\/P>\n

In this release, we\u2019ve introduced two major features:<\/FONT><\/P>\n

1. Ruled-based customization of interop assemblies<\/FONT><\/P>\n

2. TlbImp regression test tool<\/FONT><\/P>\n

Ruled-based customization of interop assemblies<\/H2>\n

The new TlbImp utility allows users to customize the interop assembly conversion process within TlbImp, by specifying a set of rules to customize specified types\/functions\/signature. We\u2019ve received a lot of feedback from TlbImp users that they want the ability to make their own changes to the interop assembly in their build process, and they end up using ILDASM to disassemble the interop assembly into IL code, modify it using a PERL script, and then use ILASM to re-generate the interop assembly. This is obviously a painful process and requires a lot of additional work. This feature is designed to solve this problem. <\/FONT><\/P>\n

Let\u2019s start with a simple example: suppose we\u2019d like to change the name of a certain type from an interop assembly. Let\u2019s first double click to open TlbImpConfigFileEditor.exe to start the config file editor, and open the type library which contains the type we want to customize \u2013 let\u2019s just use Samples\\ChangeManaged\\Name\\ChangeManagedNameSimple.tlb to illustrate this:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image002\"<\/A><\/A><\/A><\/P>\n

The left pane shows every type\/function\/signature\/field in that particular type library, while in the right pane, all the rules in the config file are displayed. All these rules tell TlbImp how to customize the interop assembly. <\/FONT><\/P>\n

In order to change the name of IComparable interface, we need to create a rule. First, let\u2019s drag the IComparable interface from the left pane to the right pane, and you will see the following dialog:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image004\"<\/A><\/A><\/A><\/P>\n

The dialog above is used to create a new rule, which tells TlbImp <\/FONT><\/P>\n

1) What types\/functions\/signatures\/fields are affected, and<\/FONT><\/P>\n

2) What kind of customization will be done<\/FONT><\/P>\n

In this dialog, we need to specify the corresponding Action to be ChangeManagedName by selecting ChangeManagedName in the drop down box, so that the name of types will be customized. After clicking OK, you\u2019ll see a rule gets created in the right pane as follows (you\u2019ll need to expand the rule node on your own):<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image006\"<\/A><\/A><\/A><\/P>\n

The rule named \u201cChange interface name\u201d has a category of type, which means this rule applies to types only, not functions, not signatures. The condition node has a sub tree defining a set of conditions which specifies what types are affected by this rule. By selecting the Condition node (or its sub nodes), you\u2019ll be able to see the corresponding expression in the bottom (read-only), which is NativeName Equal ‘IComparable. It means that any type that is named \u201cIComparable\u201d in the type library will be affected by this rule. Because we were dragging the IComparable interface node to the right side, the right set of conditions that match the interface is automatically generated for you. You can also modify the condition by yourself if you wish. Say we would like to add one restriction that the rule only applies to interfaces. Let\u2019s click the <Empty> node under the And node, select TypeKind in the first dropdown box, Equal in the second dropdown box, interface in the third dropdown box. <\/FONT><\/P>\n

The result is as follows:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image008\"<\/A><\/A><\/A><\/P>\n

Please note that the condition nodes are organized like an abstract syntax tree. Therefore, all the condition nodes under the \u2018And\u2019 node are basically \u2018And\u2019-ed together. You\u2019ll see the corresponding expression in the bottom pane, as follows:<\/FONT><\/P>\n

( NativeName Equal ‘IComparable’ ) And ( TypeKind Equal ‘Interface’)<\/FONT><\/P>\n

When the condition part is done, we\u2019ll need to specify how the customization will be done. In this case, we need to specify the new name of the type. Clicking on the New Name node under Action node, you\u2019ll get the dialog below:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image010\"<\/A><\/A><\/A><\/P>\n

Enter the new name and click OK. The rule is now completed:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image012\"<\/A><\/A><\/A><\/P>\n

Let\u2019s save it as ChangeInterfaceName.xml, and call TlbImp2.exe under command line. You\u2019ll need to use the new \/config switch to refer to the .xml file you\u2019ve just saved (as highlighted in yellow). <\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image014\"<\/A><\/A><\/A><\/P>\n

After running tlbimp2, you can start ILDASM on the result interop assembly and see what it is like after it is customized:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image016\"<\/A><\/A><\/A><\/P>\n

You\u2019ll see IComparable has been renamed to IMyInterface (as highlighted in yellow). <\/FONT><\/P>\n

Besides the ChangeManagedName action, TlbImp also supports a few other actions. A full list of supported actions is as follows:<\/FONT><\/P>\n

1. ChangeManagedName<\/B>:<\/B> Change the name of specified entity<\/FONT><\/P>\n

2. ResolveTo:<\/B> Resolve a type library type to another managed type. We already have people requesting this feature (<\/FONT>http:\/\/clrinterop.codeplex.com\/WorkItem\/View.aspx?WorkItemId=2565<\/FONT><\/A>)<\/P>\n

3. AddAttribute<\/B>:<\/B> Add attribute on any type<\/FONT><\/P>\n

4. PreserveSig<\/B>:<\/B> Apply preserveSig transformation to functions and add PreserveSig attribute<\/FONT><\/P>\n

5. ConvertTo<\/B>:<\/B> Change function signature. You can use ConvertTo to change int * to an int array.<\/FONT><\/P>\n

Every action has a corresponding example under the Samples directory. Please feel free to try out those examples if you are interested.<\/FONT><\/P>\n

Regression Test Tool<\/H2>\n

In order to help developers to make sure his change doesn\u2019t cause any regression, we\u2019ve developed a simple regression test tool, which is available at the same project page:<\/FONT><\/P>\n

http:\/\/clrinterop.codeplex.com\/Release\/ProjectReleases.aspx?ReleaseId=17579<\/FONT><\/A><\/P>\n

This is the same tool we\u2019ve been using internally for developing this new TlbImp release. <\/FONT><\/P>\n

Download and unzip the .zip file, double click to launch TlbImpRegressionTestTool.exe under bin directory, and then navigate to the file menu and open the testcase.xml under testcase directory:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image018\"<\/A><\/A><\/A><\/P>\n

You can see there is a list of all the test cases in the main window. Before running these testcases, you need to tweak some settings: Select settings under the Run menu, and enter the exact location of TlbImp2.exe and WinDiff.exe, which is required during test execution. <\/FONT><\/P>\n

Please note that you can use a different diff tool as long as the diff tool accepts two arguments and compare the diff between the two.<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image020\"<\/A><\/A><\/A><\/P>\n

After you are done with the configuration, select Run All Testcases or Run Selected Testcases under the run menu to run the testcases:<\/FONT><\/P>\n

<\/FONT><\/A>\"clip_image022\"<\/A><\/A><\/A><\/P>\n

This tool will execute the selected testcases one by one and change the status accordingly once the test finished execution. A green background means success, while a red background suggests failure. In the case of failure, you can double click on that row to open windiff (or your preferred diff tool) which compares the expected result (generated from a stable version of TlbImp) and the actual result (generated from the specified TlbImp in the configuration step). <\/FONT><\/P>\n

And that\u2019s it. Do try out these new features, and let us know what you think about this new TlbImp release. Feel free to leave comments either at this blog or directly at <\/FONT>http:\/\/clrinterop.codeplex.com\/<\/FONT><\/A>.<\/FONT><\/P>\n

 <\/P>\n

 <\/P>\n

– Yi Zhang,<\/P>\n

Developer, CLR<\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P><\/p>\n","protected":false},"excerpt":{"rendered":"

It has been a few months since our last release of TlbImp on CodePlex. We recently released a new version of TlbImp \u2013 please visit the Codeplex page for this tool to find out more. In this release, we\u2019ve introduced two major features: 1. Ruled-based customization of interop assemblies 2. TlbImp regression test tool Ruled-based […]<\/p>\n","protected":false},"author":342,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[],"class_list":["post-1883","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet"],"acf":[],"blog_post_summary":"

It has been a few months since our last release of TlbImp on CodePlex. We recently released a new version of TlbImp \u2013 please visit the Codeplex page for this tool to find out more. In this release, we\u2019ve introduced two major features: 1. Ruled-based customization of interop assemblies 2. TlbImp regression test tool Ruled-based […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/1883","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/342"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=1883"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/1883\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=1883"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=1883"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=1883"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}