Walkthrough

Web Service Software Factory v3 Community Drop (build 27)

16 April 2007

This walkthrough should act as your guide to learn about the new things in this drop. Obviously because this is the first drop, everything is new :) 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 project
  • Generate code

Setting up

  • Open your favorite email client
  • Compose a new message to dons@microsoft.com with the subject "Drop 27 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 not be there.


 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. It will likely change in a near future
 build. Any suggestions?


 Question 1:
 Would you like for a Service Contract model (ServiceContract1.servicecontract) be created by default and placed in
 the product definition project (Boeing.Model) for you? Or is having to create it manually okay?

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

  • In Solution Explorer, double-click on SCM.servicecontract to open the designer for it.
  • 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 or using the properties window.

 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.


 Question 2:
 For the operation shape, we are considering removing the "Action" property. What do you think about this? Are there
 other technology-agnostic properties you think should be added/removed?

  • 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 will
 be fixed in the next drop.

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

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


 Question 3:
 Do you have any feedback, suggestions, or general comments about using the Service Contract Designer?

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.

 Known Issue 11:
 The initial width of this shape is too narrow. It will be widened in a future build.

  • Using either the shape or its properties window, rename it to AircraftPart.

 Known Issue 12:
 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. Does this
 make sense? Would you expect something else?


 Known Issue 13:
 In the propery window, the Model Element 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.

 Question 4:
 Now that you've added a couple of properties, is clicking on the elipsis and using the type selector a reasonable way
 to do define the Data Member types? What is the most natural experience?


 Question 5:
 Does the separation of the Service Contract designer (for service-specific things) and the Data Contract designer
 (for things reusable across services) make sense? Would a different separation feel more natural? Do you have any
 other thoughts or suggestions about using the Data Contract designer?

  • 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 14:
 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 DemandNotEstablished fault.
  • In the properties window, click the elipsis for the Type property, and expand the nodes.
  • Choose DemandNotEstablishedFault and click OK.

 Question 6:
 Now that you've completed the design of the fault contract, does the process seem natural? Do you have suggestions
 for improvements?


 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 15:
 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 to be the same as the namespace of the service contract.

 Question 6:
 Does applying the technology platform at the designer level seem natural? Would you rather specify the technology
 on each individual shape? Do you have another suggestion?

  • 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 project

  • Right-click on the solution 'Boeing' and add a new C# Class Library project, called "Implementation" to the solution.

 Known Issue 16:
 In this build, there is no project mapping capability, so we recommend you create a single project to hold all
 of the code. In a future build, a recipe will unfold a configurable solution structure (like what v2 does) that
 contains projects for all of the necessary parts of the service (service interface, service implementation, data
 contracts, fault contracts, etc) and the necessary references between them.

  • Delete the Class1.cs file from the Implementation project.
  • For each of the 2 designers, click on the design surface and, using the properties window, specify the Project.

 Known Issue 17:
 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

  • 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 18: 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".
  • On the service contract designer, right-click on the design surface and choose "Generate Code".

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


 Known Issue 19:
 There are a number of context menu items that you might see ... and don't work yet. Specifically, if you
 right-click on the service contract design surface, you will see "Import WSDL into DSL model". Selecting it will
 throw an exception, but it will work in future builds.

  • 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 26, 2007 at 9:39 PM by donsmith, version 4

Comments

No comments yet.