This project is read-only.

Walkthrough

Web Service Software Factory v3 Community Drop (build 38)

27 April 2007

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. 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

  • Setting up
  • Create solution
  • Model the service
  • Model the data contracts
  • Wire up the data contracts
  • Define the technology
  • Create the projects - (UPDATED FOR THIS DROP)
  • Generate code - (UPDATED FOR THIS DROP)

Setting up

  • Open your favorite email client
  • Compose a new message to dons@microsoft.com with the subject "Drop 38 feedback".
  • Copy the questions into the new email message.
  • Please complete the questions as you encounter them in this walkthrough.

Create solution

 Known Issue 0:
 This is a blanket known issue. We know there is a lot of model and data validation that is not taking place yet. 
 If you try to break something, you will likely succeed. There are also a number of things that may be missing from 
 the generated code in this build. Don't worry about bringing it to our attention yet (we probably know about it). 
 If you find a bug with this in a future build, please bring it to our attention.

  • Open Visual Studio in the experimental hive, Choose File -> New -> Project...
  • Under Project types, select Guidance Packages/Services Software Factory

 Known Issue 1:
 You'll also notice there is also a root "Services Factory". 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 will be removed in future drops. Actually, "Services
 Software Factory" will be renamed too. We're not yet sure what it will be.

  • For the Name, type Boeing and then click OK
  • On the Solution Options step, choose Finish

 Information 1:
 If you used a previous version of the Service Factory, you'll notice that instead of the 9 projects that were
 initiallycreated before, now only one project is created. This is a custom project and is called the Product
 Definition. In this drop it only has the responsibility of holding all of the models, but in future drops it will
 define project mappings and have other responsibilities.

Model the service

  • In Solution Explorer, right-click on Boeing.Model and choose Create Model

 Known Issue 2:
 When you right-click on the Boeing.Model project, you will see many other menu items too. In this build, none of
 these work so it is recommended you don't use them. In future builds they will either not be there or they will work.


 Known Issue 3:
 Once these models are created, there is no way to remove/delete them. Yes, this is a bug that will be fixed in a
 future drop.


 Information 2:
 We're not crazy about appending ".Model" on the end of the project name. Based on customer and community feedback,
 It will stop being appended at some community drop in the future.

  • Choose "Service Model" and name it "SCM" ... click Finish

 Information 3:
 If you used a previous version of the Service Factory, you'll notice that instead of the 9 projects that were
 initiallycreated before, now only one project is created. This is a custom project and is called the Product
 Definition. In this drop it only has the responsibility of holding all of the models, but in future drops it will
 define project mappings and have other responsibilities.

  • From the toolbox, drag an Operation onto the design surface

 Information 4:
 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 modelled and evolve without defining what service it will be associtated 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.

 Known Issue 4: 
 In the properties window, "Namespace" will be removed in the future since this is something that will be associated
 with the service contract.

  • On the GetRequirementDemand shape, right-click on Faults and choose Add new Fault.
  • Name the DemandNotEstablishedFault
  • From the toolbox, drag a MessageContract shape onto the design surface.
  • Name the new shape "DemandRequest"
  • On the shape, right-click on "Parts" and choose "Add new Message Part"
  • Name the message part "AircraftPart"

 Known Issue 5:
 In this drop, there is no way to add a part that is a primative type to a message contract. This will be fixed in a
 future drop. There is also no way to specify that a part is a collection of a particular type.

  • From the toolbox, drag another MessageContract shape onto the design surface.
  • Name the new shape "DemandResponse"
  • On the shape, right-click on "Parts" and choose "Add new Message Part"
  • Name the message part "PartLevel"
  • In the toolbox, click on the ConnectTool and click-drag from DemandRequest to GetDemandRequirements.
  • In the toolbox. click on the "ConnectTool" again and click-drag from the operation to the response message.
  • Notice how the arrows indicate the message flow to and from the operation (based on the direction of your click-drags).

 Known Issue 6:
 Unfortunately the request and response message properties in the operation's property window are backwards. This 
 causes the code generated to also be backwards. This will be fixed in the next drop - not sure how it slipped 
 through the cracks on this drop (since we knew about it in the last drop). Doh.

  • In the toolbox, drag the "ServiceContract" shape onto the design surface.
  • Using either the shape or its properties window, rename it to PartsMgmtServiceContract.

 Known Issue 7:
 In the properties window of the service contract shape, the namespace propertiy should have a default namespace value
 based on the project prefix defined in the first recipe (Boeing.Services). This will be fixed in future builds.

  • In the properties window, provide a namespace value of http://boeing.com/scm/2007/04
  • In the toolbox. click on the "ConnectTool" and then click-drag from the service contract to the operation.

 Known Issue 8:
 Because this connection is not direction-specific, you should be able to drag this connector in either direction.
 This will be fixed in future builds.

  • In the toolbox, drag the "Service" shape onto the design surface. This represents the service's implementation.
  • Name the new shape PartsMgmtService.

 Known Issue 9:
 In this build, the property window also contains "Binding Style" and "Encoding". These will be removed in a future
 build. This level of detail (lack of abstraction) has no business in the model. "Address" will also be removed
 since this is a deployment/host property.

  • In the toolbox. click on the "ConnectTool" and then click-drag from the service to the service contract.

 Known Issue 10:
 Because this connection is not direction-specific, you should be able to drag this connector in either direction.
 This will be fixed in future builds.

Model the data contracts

  • In Solution Explorer, right-click on Boeing.Model and choose Create Model.
  • Choose the "Data Contract Model", name it "CommonTypes", and click Finish.
  • From the toolbox, drag a DataContract shape onto the design surface.
  • Using either the shape or its properties window, rename it to AircraftPart.

 Known Issue 11:
 In the propery window, the Namespace property has the wrong default value (it should be based on the project prefix)
 and the Object Extender Container property should not ever be visible in the property window (for any shape). It will
 be removed in a future build.

  • From the toolbox, drag another DataContract shape onto the design surface.
  • Using either the shape or its properties window, rename it to Vendor.
  • On the Vendor shape, right-click on Properties, and choose "Add new primative Data Element" and name it Name.

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


 Known Issue 12:
 In the propery window, the Object Extender property should not be visible and will be hidden in a future build.

  • From the toolbox, drag another DataContract shape onto the design surface.
  • Using either the shape or its properties window, rename it to DemandNotEstablishedFault.
  • On the DemandNotEstablishedFault shape, right-click on Properties, and choose "Add new primative Data Element"
  • Name the new property ModuleManager and leave the type System.String.
  • Click the Data Contract Connector in the toolbox and click-drag from the Vendor to the AircraftPart.

 Information 6:
 In this build, the model constraints are preventing circular references between data contracts, but once we work out
 the code generation issues, we'll remove this constraint.

  • In the AircraftPart shape, rename the new Vendor property to PreferredVendor (this represents the property name).
  • From the toolbox, drag another DataContract shape onto the design surface.
  • Using either the shape or its properties window, rename it to PartLevel.
  • On the PartLevel shape, right-click on Properties, and choose "Add new primative Data Element" and name it OnhandLevel.
  • Using the properties window, change the type of this property to a System.Int32 by using the elipsis.
  • On the PartLevel shape, add another property called IncomingLevel of type System.Int32.
  • Save the data contract model

Wire up the data contracts

  • Return to the SCM.servicecontract designer.
  • On the DemandRequest shape, click the AircraftPart part.
  • In the properties window, click the elipsis for the Type property, expand the nodes, choose AircraftPart, and click OK.

 Known Issue 13:
 The value of the Type property will (hopefully) become shorter and much more clear in a future build.

  • On the DemandResponse shape, click the PartLevel part.
  • In the properties window, click the elipsis for the Type property, expand the nodes, choose PartLevel, and click OK.
  • On the GetRequirementDemand operation shape, choose the DemandNotEstablishedFault.
  • In the properties window, click the elipsis for the Type property, and expand the nodes.
  • Choose DemandNotEstablishedFault and click OK.

 Information 7:
 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 both of the designers (SCM.serviceontract and CommonTypes.datacontract).

Define the technology

  • Click on the surface of the service contract designer.
  • In the property window, choose "WCF Extension" as the Implementation Technology.

 Information 8:
 At this point, each of the shapes on the designer now have new properties that are specific to WCF.

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

 Information 9:
 The easiest way to see which properties are specific to WCF are to put the properties window in catagory view
 rather than alphabetically sorting them.


 Known Issue 14:
 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.

  • Change the namespace of the service to be the same as the namespace of the service contract.
  • Open the data contract designer and click on the design surface.
  • In the property window, choose "WCF Extension" as the Implementation Technology.

 Information 10:
 Now the properties for each of the data contracts have new properties that are specific to WCF. Wow, that was
 kinda confusing. In other words, if you click on "OnhandLevel" you will now see it has properties for "Order"
 and "IsRequired".

Create the projects (UPDATED)

  • Right-click on the solution 'Boeing' and add a new solution folder with the name "WCF"
  • Right-click on the WCF solution folder and add 3 new C# Class Library projects with the following names:
    • DataContracts
    • ServiceContracts
    • ServiceImplementation
  • Delete the initial Class1.cs files from each of the projects.

 Information 11:
 In the future we will supply a recipe that will generate your solutions structure for you so you will not have
 to manually create and name each of the implementation projects.

  • Right-click on the WCF solution folder and choose Services Software Factory -> Populate Project Mapping Table
  • For the Mapping Table Name, type in "WcfProjectMapping" and click Finish
    • If prompted, choose yes to reload the ProjectMapping.xml file

 Information 12:
 That Populate Project Mapping Table recipe created a new mapping table in the ProjectMapping.xml file. Because
 we named each of the projects the way we did, the recipe was able to infer what each of these projects should
 be used for and map the correct role to the appropriate project. The following list shows each of the roles
 and the necessary suffix that you must use if you want the recipe to infer the mapping:

   A project with this suffix          will get this role
   --------------------------          ------------------
   Host                                HostRole                
   DataContracts                       DataContractsRole
   FaultContracts                      FaultContractRole
   MessageContracts                    MessageContractRole
   ServiceContracts                    ServiceContractRole     
   ServiceImplementation               ServiceRole             

 If you don't use these suffixes, you'll have to supply the role manually yourself by editing the 
 ProjectMapping.xml file. In a future build, we will supply a mapping editor recipe.


 Known Issue 15:
 In the roles/suffixes above, you will see a FaultContractsRole. In this drop, there is not a way to use this 
 role. In a future build, we will be adding a FaultContract shape to the Data Contract designer so faults
 and data contracts can be modeled independently.

  • For each of the 2 designers, click on the design surface and, using the properties window, choose WcfMappingTable as

the Project Mapping Table.

 Known Issue 16:
 When viewing the properties window after clicking on the design surface, you will see a blank Name property.
 This property will be removed in future builds. It just doesn't make sense to be there.

Generate code (UPDATED)

  • On the data contract designer, right-click on the PartLevel shape and choose "Generate Code".
  • After reviewng the code, change the namespace on the PartLevel shape, and then regenerate the code.

 Known Issue 17: 
 For this build, provide a reasonable namespace. If you try to break it, you will likely succeed. The future has 
 better validation facilities in place ;)

  • Right-click on the design surface and choose "Generate Code".

 Known Issue 18: 
 During code generation, you may notice various exceptions in the output window. Just ignore them for now.
 We're looking into them and will resolve them later. They don't seem to have a negative impact on code gen.

  • Open the ProjectMapping.xml file and look for the ProjectMapping element that has the role of ServiceContractRole.
  • Add the MessageContractRole to this ProjectMapping element. It should look like this when you are finished:

        <ProjectMapping ProjectId="some random guid" ProjectPath="\">
          <Roles>
            <Role Name="ServiceContractRole" />
            <Role Name="MessageContractRole" />
          </Roles>
        </ProjectMapping>


 Known Issue 19: 
 Obviously because you had to manually do that previous 2 steps, we have a bug during the population of the
 project mapping table.

  • On the service contract designer, right-click on the design surface and choose "Generate Code".

 Information 13:
 You can also generate code from any shape and it (if appropriate) and its dependencies will be regenerated.

  • 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 Apr 28, 2007 at 5:06 AM by donsmith, version 1

Comments

No comments yet.