Introductory Walkthrough

Web Service Software Factory v3 Community Drop (build 117)


This walkthrough should act as your guide to learn about the new things in this drop. It does this by building on previous walkthroughs, and changes or adds steps to highlight the new capabilities of the drop. We'll try to show you everything it does without letting you fall prey to something that isn't working yet. We've also tried to forecast some of your questions and answer them here.

There are 2 ways you can complete this walkthrough: you can complete it by hand from start to finish, or you can use the file provided here and use the starter solutions inside it to only complete the exercises you want to. Hopefully this will save time for those of you who have completed it in the past. We’ll mark the exercise that have changed and are new below.

Drop us a note on the discussion forum if you have a question and feel free to post a bug to the issue tracker if you find something that hasn't been identified as a known issue.

Contents

  • Exercise 0: Setting up
  • Exercise 1: Create solution
  • Exercise 2: Model the service
  • Exercise 3: Model the data contracts
  • Exercise 4: Wire up the data contracts
  • Exercise 5: Define WCF technology
  • Exercise 6: Create WCF projects
  • Exercise 7: Generate WCF code
  • Exercise 8: Import a service contract
  • Exercise 9: Build ASMX services
  • Exercise 10: Model host and client

Exercise 0: Setting up

  • In a new browser tab or browser window, navigate to this page.
  • Using the comment field at the bottom of that page, please provide numbered responses to the questions as you encounter them in this walkthrough. Guy provides a good example here. Sorry that the comment box does not support any formatting.
  • As you go through this walkthrough, you shouldn’t hit any bugs that aren’t identified as known issues. However, if you think you find an unidentified bug in your own use of the drop, please log it in the issue tracker.
  • If you like, you can download the starter and solution files for this walkthrough here.

Exercise 1: Create solution

Known Issue
This is a blanket known issue. We know there is some model and data validation that is not taking place yet. With that said, we have included a model validation framework and a number of validation rules. Please let us know if you’re able to do something you don’t think you should be able to or if you hit a rule you don’t think you should.

  • Open Visual Studio in the experimental hive, point to File, point to New, and choose Project...
  • Under Project types, select Guidance Packages/Services Software Factory

Known Issue
You'll notice there is also a root "Services Factory" node. This is a byproduct of the custom project you'll see in a minute. Just ignore this and don't use it. It is a bug and may be removed in future drops. Actually, "Services Software Factory" will be renamed too. We're not yet sure what it will be – probably something like “Service Factory: Modeling Edition”

  • For the Name, type BlueYonderAirlines and then click OK
  • On the Solution options step, click Finish.

Exercise 2: Model the service

  • In Solution Explorer, right-click on BlueYonderAirlines, point to Add and select New Model…
  • Choose ServiceModel and in the textbox, enter MaterialMgmt, and click Finish.
  • From the toolbox, drag an Operation shape onto the design surface

Information
Earlier versions of the Service Factory required the service interface be understood before using the software factory. By modeling the operation shape independently (rather than including it as a property of the service contract) the functional requirements can be modeled and evolve without defining what service it will be associated with.

  • Rename the shape to GetRequirementDemand. You can do this by double-clicking on it, using the properties window, or just selecting the shape and begin typing.
  • On the GetRequirementDemand shape, right-click on Faults and click Add new Fault.
  • Name the fault DemandNotEstablishedFault
  • From the toolbox, drag a Message Contract shape onto the design surface and name it DemandRequest
  • On the shape, right-click on Parts and click Add new Data Contract Message Part
  • Name the message part AircraftPart
  • On the shape, right-click on Parts and click Add new Primitive Message Part
  • Name the message part Date, and using the Properties window, assign its type to be System.DateTime
  • Download the PartLevel.xsd file to a location on your machine (C:\) from this address: http://www.codeplex.com/servicefactory/download?DownloadId=13287
  • Right-click on the Schemas solution folder, select Add, and choose Existing Item…
  • Locate the PartLevel.xsd file you just saved and choose Add.
  • Close the PartLevel.xsd file.
  • From the toolbox, drag an XSD Message Contract shape onto the design surface.
  • Name the new shape DemandResponse
  • On the shape, right-click on Parts and click Add new XSD Element Message Part and name the message part PartLevel.

Known Issue
If you don’t see the menu item, right-click on the shape, select Add, and choose XSD Element Message Part. This is an intermittent issue with the DSL toolkit.

  • In the Properties window for PartLevel, select the ellipsis in the Element value box.
  • Navigate into the PartLevel.xsd schema and choose the PartLevel element.
  • In the toolbox, click on the Connect Tool and click-drag from the DemandRequest message contract to the GetRequirementDemand operation.

Information
Notice how the direction you drag the Connect Tool determines whether the message is a request or response. That’s right, the arrow is actually modeling flow rather than dependency or any other UML-ism. We’re interested in your feedback about this.

  • In the toolbox, click on the Connect Tool again and click-drag from the operation to the response message.
  • In the toolbox, drag the Service Contract shape onto the design surface.
  • Using either the shape or its properties window, rename it to PartsMgmtServiceContract.
  • In the properties window, provide a Namespace value of http://blueyonderairlines.com/scm/2007/08

Known Issue
The namespace property should have a default namespace value based on the project prefix defined in the first recipe (BlueYonderAirlines). This will be fixed in future builds. Also, there is a bug in this build that causes the value you provide to not be saved. This bug has already been fixed, but just didn’t make it into this build. You’ll see it in the next drop.

  • In the toolbox, click on the Connect Tool and connect the service contract to the operation.
  • In the toolbox, drag the Service shape onto the design surface. This represents the service's implementation.
  • Name the new shape PartsMgmtService.
  • In the toolbox, click on the Connect Tool and then connect the service to the service contract.
  • Save MaterialMgmt.servicecontract model

Exercise 3: Model the data contracts

  • In Solution Explorer, right-click on BlueYonderAirlines , point to Add and select New Model…
  • Choose the DataContractModel, name it CommonTypes, and click Finish.
  • From the toolbox, drag a Data Contract shape onto the design surface.
  • Using either the shape or its properties window, rename it to AircraftPart.

Known Issue
In the Properties window, the Namespace property should be based on the project prefix.

  • From the toolbox, drag another Data Contract shape onto the design surface.
  • Using either the shape or its properties window, rename it to Vendor.
  • On the Vendor shape, right-click on Data Members, choose Add new Primitive Data Element and name it Address.

Information
The IsDataMember property is provided to allow you to model class properties independently of data members.

  • From the toolbox, drag another Data Contract shape onto the design surface and name it Contact.
  • On the Contact shape, right-click on Data Members, and click Add new Primitive Data Element and name it Name.
  • On the Contact shape, right-click on Data Members, and click Add new Primitive Data Element and name it PhoneNumber.
  • From the toolbox, drag a Data Contract Enumeration shape onto the design surface and name it PhoneNumberType.
  • On the PhoneNumberType shape, right-click on Values, and add a value called Home. Do the same to add Office and Mobile values.
  • Choose the Aggregation connector in the toolbox and click-drag from the PhoneNumberType shape to the Contact shape.
  • From the toolbox, drag a Data Contract Collection shape onto the design surface and name it Contacts (with an “s”).
  • In the Properties window of the Contacts shape, choose Contact as the value for the Data Contract property.

Information
When you provided a value for the Data Contract property, a relationship connection was drawn on the designer between the Contact and Contracts shapes.

  • Choose Aggregation in the toolbox and click-drag from the Contacts shape to the Vendor shape.
  • Choose Aggregation in the toolbox and click-drag from the Vendor shape to the AircraftPart shape.
  • In the AircraftPart shape, rename the new Vendor property to PreferredVendor (this represents the property name).
  • From the toolbox, drag a Fault Contract shape onto the design surface.
  • Using either the shape or its properties window, rename the shape to DemandNotEstablishedFault.
  • On the DemandNotEstablishedFault shape, right-click on Fault Members, and click Add new Primitive Data Element.
  • Name the new property ModuleManager and leave the type System.String.
  • For each of the shapes on the design surface, supply http://blueyonderairlines.com/types/2007/08 as the value of the* Namespace *property
  • Save the data contract model.

Exercise 4: Wire up the data contracts

  • Open the MaterialMgmt.servicecontract designer.
  • On the DemandRequest shape, click the AircraftPart part.
  • In the Properties window, click the ellipsis for the Type property, expand the nodes, and select the AircraftPart node, and click OK.

Known Issue
The value of the Type property will (hopefully) become shorter and much clearer in a future build (instead of mel://Microsoft ….)

  • On the GetRequirementDemand operation shape, choose the DemandNotEstablishedFault fault.
  • In the Properties window, click the ellipsis button for the Type property, expand the nodes.
  • Choose the DemandNotEstablishedFault fault and click OK.

Information
Up to this point, you have defined the entire service interface and still haven't made any technology (ASMX/WCF) or language (VB/C#) decisions.

  • Save MaterialMgmt.servicecontract.

Exercise 5: Define WCF technology

  • Open the MaterialMgmt.servicecontract designer and click on the design surface
  • In the Properties window, select WCF Extension as the Implementation Technology.

Information
At this point, each of the shapes on the designer has new properties that are specific to WCF.

  • Click on each of the shapes and inspect their new properties.

Information
The easiest way to see which properties are specific to WCF is to put the Properties window in category view rather than alphabetically sorting the properties in the window.


Known Issue
The Namespace property for the service should become the same namespace property as the service contract it is implementing or at least use the project prefix. Also, the Namespace property should not be a technology extension property (in other words, in the WCF Settings section of the Properties window. It will be moved to the Misc section and given the right value in a future build.

  • Change the Namespace of the service to http://blueyonderairlines.com/scm/2007/08
  • Save MaterialMgmt.servicecontract
  • Open the CommonTypes.datacontract designer and click on the design surface
  • In the Properties window, select WCF Extension as the Implementation Technology.
  • Click on each of the shapes and inspect their new properties.
  • Save CommonTypes.datacontract

Exercise 6: Create WCF projects

  • Right-click on the BlueYonderAirlines solution, point to Add, and select WCF Implementation Projects…
  • In the Add New Project dialog, enter WCF as the Name, and select* OK*

Known Issue
If you save projects in a directory such that the fully qualified project name is greater than 260 characters, you will encounter an error when the template is unfolded. We encourage you to create them in a short path name.


Information
It is our understanding many teams will want to influence the format of the solution structure of the implementation projects. A separate walkthrough for how to accomplish this is available on the codeplex community site.


Information
In addition to unfolding a number of implementation projects, the ProjectMapping.xml file was also updated so the code generation process will know where to place the generated code.

  • Open the CommonTypes.datacontract designer and click on the design surface.
  • In the Properties window, for the Project Mapping Table property, choose WCF
  • Open the MaterialMgmt.servicecontract designer and click on the design surface.
  • In the Properties window, for the Project Mapping Table property, choose WCF
  • Save both files

Exercise 7: Generate WCF code

  • For each of the data and fault contracts on the data contract designer (CommonTypes.datacontract), provide an Order value for each data or fault member starting at 1. If you forget one or have a duplicate within a data contract, a validation rule will let you know when you try to generate code.
  • Right-click on the PhoneNumberType shape and select Generate Code.
  • Notice how a validation rule is preventing code generation. Select the Contacts collection shape. In the Properties window, choose List<T> as the Collection Type value to satisfy the validation rule. Now try to generate code for the PhoneNumberType again.

Known Issue
In a future build, None will not be an option for the Collection Type and List<T> will be the default value.

  • Reviewing the code that was generated. You will find it in the Solution Explorer under the path WCF/Source/Service Interface/WCF.DataContracts/GeneratedCode
  • Change the namespace on the PhoneNumberType shape to http://blueyonderairlines.com/types/2007/08, regenerate the code, and take note of the change in code.

Known Issue
If you now open this file, it will indicate that it has been changed even before you change it. When you close it, Visual Studio will prompted you to save changes. If you choose not to save changes, doing so will delete the contents of the file. This is a bug that will be fixed in a future build. Fortunately, you can re-generate (

  • Generate all of the data contracts by right-clicking on the surface of the data contract designer and select Generate Code.
  • Open the MaterialMgmt.servicecontract designer and select the GetRequirementDemand operation.
  • Change the ReplyAction property to be the same value as the Action property.
  • Right-click on the surface of the service contract designer and select Generate Code.

Information
You can also generate code from any shape and (if appropriate) its dependencies will be regenerated (unless those dependencies cross models).

Exercise 8: Import a service contract

  • In Solution Explorer, right-click on BlueYonderAirlines, select Add, and select New Model…
  • Select Service Model, name it VendorGateway, and click Finish.
  • After the designer is created and opens, click on the design surface, and in the Properties window, select WCF Extender as the value for the Implementation Technology property

Known Issue
The fact that you have to choose an implementation technology before you can import a WSDL document is a bug that will be fixed in the next build.

  • Right-click on the design surface and select Import from WSDL.

Known Issue
The Import from WSDL dialog should not be asking for the data contract model since it is no longer being used for imported services. This will be removed from the dialog in a later drop.


Known Issue
Before the import is finished, a dialog will prompt you to reload the XSD file. This is a bug that will be fixed in a later release. Choose Yes to close the dialog box.


Information
An XSD file that represents the types passed to and from the service has been saved to the Schemas solution folder.

Exercise 9: Build ASMX services

This exercise has you perform the same steps as exercises 5, 6, and 7 except to build ASMX services instead of WCF services. The same Known Issues apply to this exercise.

Define ASMX technology
  • Open each of the 3 designers:
    • CommonTypes.datacontract
    • MaterialMgmt.servicecontract
    • VendorGateway.servicecontract
  • Click on the surface of the designer.
  • In the Properties window, select ASMX Extension as the Implementation Technology.
  • Do this for the other 2 designers.
  • Save each of the model designers.

Create ASMX projects

  • Right-click on the BlueYonderAirlines solution, point to Add, and select ASMX Implementation Projects …
  • In the Add New Project dialog, enter ASMX as the Name, and select* OK*
  • Open the CommonTypes.datacontract designer and click on the design surface.
  • In the Properties window, for the Project Mapping Table property, choose ASMX
  • Repeat the previous step for the other 2 designers.
  • Save each of the model designers.

Generate ASMX code

  • For each of the data and fault contracts on the data contract designer (CommonTypes.datacontract), provide an Order value for each data or fault member starting at 1. If you forget one or have a duplicate within a data contract, a validation rule will let you know when you try to generate code.
  • Select the Contacts collection shape. In the Properties window, choose List<T> as the Collection Type value.
  • On each of the designers, right-click on the design surface and click Generate Code.

Exercise 10: Model host and client

  • In Solution Explorer, right-click on BlueYonderAirlines, point to Add and select New Model…
  • Choose HostDesignerModel, type in Deployment, and click Finish
  • From the toolbox, drag a HostApplication onto the design surface and name it IIS. This represents the host application that will be listening for messages.
  • In the Properties window of the IIS shape, choose ASMX Extensions as the Implementation Technology.
  • For the value of the Implementation Project property, select the drop-down box, select ASMX\Source\Service Interface\C:\...\ASMX.Host\
  • Drag a Service shape from the toolbox and drop it on the IIS host. They will be automatically associated. In future builds, the experience will also be consistent with the other designers. The Service shape represents a reference to the service this host will provide access to. Name the Service MaterialMgmt.
  • In the Properties window for MaterialMgmt, select the ellipsis for the Service Contract Type value.
  • Select the PartsMgmtService service under the MaterialMgmt node and choose OK.
  • Drag an Endpoint from the toolbox and drop it on the MaterialMgmt shape.
  • From the toolbox, drag a ClientApplication onto the design surface and name it ScmWinformClient.
  • In the Properties window of ScmWinformClient, choose ASMX Extensions for the value of the Implementation Technology.
  • Drag a Proxy from the toolbox and drop it on the ScmWinformClient shape. This represents the code that invokes the service.
  • Select the Proxy Endpoint Connecctor tool (misspelled :) from the toolbox. Click-drag from the Proxy shape to the service’s Endpoint.
  • Right-click on the design surface and choose Generate Code.
  • This designer is obviously not yet finished, but we wanted to provide you a visualization of it early. Please spend some time looking at the few properties on each of these shapes and connectors as well as think about what you would like to model on this designer. Please send us your feedback.
  • Okay, all done. Thank you for sending the feedback.
    • Feel free to add more that isn't related to the questions.
    • For example, was this walkthrough useful?

Last edited Aug 13, 2007 at 10:00 PM by donsmith, version 11

Comments

Tyxou Sep 7, 2007 at 1:04 PM 
The connector does not seems to work if you are in a dual screen configuration (or) with a floating toolbox : Try docking your toolbox before attempting to draw a connector.

sgentile Sep 4, 2007 at 7:01 PM 
The Connector types are almost impossible to get on the surface

sgentile Sep 4, 2007 at 6:56 PM 
I am going through it right now and am up to Exercise 3. I really love the modeling stuff! Give me a shout when you can!

an_phu Aug 8, 2007 at 7:38 AM 
Exercise 8: The "WCF Extender" Implementation Technology was not available in the drop down box.


Exercise 12: Typo? Instead of MaterialMgmtRef, should be MaterialMgmt?
> Drag an Endpoint from the toolbox and drop it on the MaterialMgmtRef shape.

Unable to select service contract type for the Service shape.


Some obvious comments:
* the Implementation Project and Implementation Technology in the Properties windows should be human-readable string instead of a guid.
* the schema files for the ServiceContractDsl and DataContract are missing.


The walkthru gives a nice little intro to what Service Factory v3 is capable of.

dennismulder Jul 22, 2007 at 7:52 PM 
Small leftover from previous version:

With the exception of PartLevel, for each of the shapes on the design surface, supply *http://blueyonderairlines.com/types/2007/06 as the value of the Namespace *property

The PartLevel is not yet there!! Text should be:

For each of the shapes on the design surface, supply *http://blueyonderairlines.com/types/2007/06 as the value of the Namespace *property