Walkthrough: Adding a Property to an Existing Technology Extender

This walkthrough introduces you to a new property on a ModelElement and uses the property from within a TT-template.

Introduction

In this walkthrough, you will add a property called DocumentComment to a ServiceContract element using the WcfTechnologyProvider. When you are finished, you will be able to add custom Properties to a Technology Provider and access these from within a TT-template. The result of this walkthrough is shown in Figure 1.
DocumentCommentInGrid.png
DocumentCommentInCode.png
Figure 1: Adding a comment to the DocumentComment property in the Property Window.

Prerequisites

In order to complete this walkthrough, you will need to:
  1. Have the Service Factory source code installed on your computer.
  2. Have a copy of the Service Factory source code registered and installed within Visual Studio’s Experimental Hive.
  3. Be familiar with the basic usage scenarios for the Services Factory.

Procedures

This walkthrough requires you to:
1. Modify the ServiceContractDsl project as follows:
  • Modify WCFServiceContract.cs
  • Modify ServiceContract.tt
  • Add a reference to System.Design
2. Re-build the ServiceContractDsl
3. Test the new DocumentComment property added to the ServiceContract model element.

To modify the ServiceContractDsl project
1. Open the Service factory solution Service Factory Guidance package.sln
2. Open the WCFServiceContract.cs file (located under “DSLs\Service Contract\ServiceContractDsl\Extensions\WCF\” in the Solution Explorer).
The WCFServiceContract class contains all the properties that are added by the WCFTechnologyProvider to a ServiceContract Element. Because we want your new property to be part of the ServiceContract Element and we decided to extend the WCFTechnologyProvider, the walkthrough starts here.
3. In the WCFServiceContract class, add a new property called DocumentComment as shown in the following code:
 private string documentComment = string.Empty;
 public string DocumentComment
{
    get { return documentComment; }     
    set { documentComment = value; }
}

This property will contain the XML Document Comment for a specific Service Contract element. Whenever the Model is saved, all the properties on this class will be serialized using the XmlSerializer and stored as part of the model. To support the serialization process, you should decorate your property with a custom attribute that specifies how the value should be serialized.
4. Add the following custom attribute to your newly created property:
[XmlElement("DocumentComment")]
public string DocumentComment
{
    ...
}


At this point, you should be able to rebuild the ServiceContractDsl project and see the new property in the "Property window" after selecting a ServiceContractElement (that uses the WCFTechnologyExtender). Please make sure that if you are rebuilding the ServiceContractDsl you need to close all running instances of Visual Studio that use the Services Factory.

After typing some text in the Property Window and saving the model, the value of the property is stored in the Model. Closing and re-opening the model should display the value that was saved, prior to closing the model.
Because your new DocumentComment property will appear in the property window as a single textbox without a category, you may want to improve the way this property is shown in the Property window. The way properties are shown in the Property window can be customized using a wide range of attributes, contained in the System.ComponentModel namespace. To keep this walkthrough simple, add a category to the property and specify the DocumentComment to be edited in a multiline string editor as shown in Steps 5 and 6.
5. Add a reference to the System.Design assembly. This assembly contains the MultiLineStringEditor.
To add the reference:
  • In the Solution Explorer window, expand the DSLs folder, expand the ServiceContract folder, expand the ServiceContractDsl project, right-click References, and then click Add Reference.
  • In the Add Reference dialog box, click the .NET tab and select the System.Design dll. Click OK.
6. Add the following two attributes to your DocumentComment property.
[Category("My Properties")]
[Editor(typeof(System.ComponentModel.Design.MultilineStringEditor), typeof(UITypeEditor))]
[XmlElement("DocumentComment")]
public string DocumentComment
{
   ...
}

Because you now have the ability to save and a good experience for editing the DocumentComment value, you should actually do something with this information when you are generating code.
Note: Code generation for the Service Contract is done through a TextTemplate. For more information on how these templates work, see Architecture of Text Templates on MSDN.
7. Open the ServiceContract.tt file(located under “DSLs\Service Contract\ServiceContractDsl\TextTemplates\WCF\CS\” in the Solution Explorer).
Because a XML Document Comment potentially contains line breaks and within the source code, every new comment line begins with three slashes (///), you need to add a function that formats this string appropriately as shown in the following code.
  • In the ServiceContract.tt file, add the following function to the text template, after the last “#>” on the bottom of the file. This will format your document comment correctly.
 <#+
     private static string FormatStringAsMultilineDocumentComment(string comment)
     {
         if (string.IsNullOrEmpty(comment)) return string.Empty;
 
         System.Text.StringBuilder commentBuilder = new System.Text.StringBuilder();
         foreach (string partOfComment in comment.Split(new string[] { "\n", Environment.NewLine }, StringSplitOptions.None))
         {
             string line = string.Concat("/// ", partOfComment, Environment.NewLine, "\t");
             commentBuilder.Append(line);
         }
         int padR = Environment.NewLine.Length + 1;
         return commentBuilder.ToString(0, commentBuilder.Length > padR ? commentBuilder.Length - padR : commentBuilder.Length);
     }
 #>


You can add the following line to access the value of the comment you specified in the model, from within a TextTemplate:
<#= CurrentExtender.DocumentComment #>

Add the statement that will output the formatted XML Document Comment in between the <summary> tags.

/// <summary>
 <#= FormatStringAsMultilineDocumentComment(CurrentExtender.DocumentComment) #>
 /// </summary>
 [WCF::ServiceContract(Namespace = "<#= CurrentElement.Namespace #>", ...]
 public partial interface I<#= CurrentElement.Name #>


8. Save your changes, close any running instances of the Services Factory, and re-build the ServiceContractDsl project.
To test the new DocumentComment property added to the ServiceContract model element
9. Once you successfully rebuild the ServiceContractDsl project, do the following:
  • Open a new instance of Visual Studio in the experimental hive.
  • Add a new Model Project.
  • Add a new Service model to the project.
  • Choose "WCF Extension" as the implementation technology.
  • Add a service contract to the model and view its properties in the Properties window, there you will see the property added in this walkthrough.
  • Enter a value for the DocumentComment property.
  • Add additional elements to the Services Model and make sure the model is valid.
  • After generating code for this model, you should be able to see the value entered in the Properties window within the generated source code.

Last edited Jun 7, 2007 at 11:29 PM by ndelgado, version 2

Comments

No comments yet.