Don Smith : Work Related

Updating the factories to VS2010

donsmith — Fri, 06 Nov 2009 00:10:00 GMT

This is just a quick post to let you know that I just posted an update over on the p&p team blog. Since this effort spans GAT/GAX and 3 factories, it makes more sense to post the updates there instead of here. Sorry for any confusion. Feel free to ping me if you have any questions. I'll still be blogging here (hopefully more) just not about the factory refresh project. Thanks.

Data Access Guidance

donsmith — Fri, 24 Jul 2009 03:26:00 GMT

A few of us in patterns & practices, with some help from our partners on the Data Platform team have been working on some guidance to help .NET customers build data access layers (DALs). We’ve been hearing for a while that data access on the .NET platform is not intuitive and this confusion is related to technology choices, approaches, design decisions, and implementations. So in response, we putting together some guidance that will hopefully reduce the confusion.

High-level Description

The role of the DAL is to consume services* that save and retrieve data on behalf of the application. Preferably it’s loosely coupled from the application through interface definitions provided by the application layer. Often the service it’s consuming is a SQL Server (TDS/T-SQL), which implies a relational store, and there are lots of APIs to use to do this (like ADO.NET). Other times – like when you can’t get to the SQL Server or when you’re using something other than a relational store – it’s a different kind of service or one you must build yourself (e.g. REST).

* I draw a distinction between these data services and services that represent course-grained business processes and operations (think SOA, SOAP, and things in that vein). I’m not talking about business services, but I am talking about crossing tiers.

There are quite a few factors that will influence the type of store you use and the services used to interact with the store. While I personally believe our industry needs (and is continuing to go through) a reassessment of various data storage solutions, that’s not the aim of this guidance project – we just don’t have the experience and resources to do an adequate job right now. So this project is scoped to address relational stores and custom data services.

Assuming a relational store, the app will either be able to access the SQL Server directly, or it won’t. This guidance will address both of these scenarios. In the case of being able to go straight to the SQL Server, there are 2 high-level patterns for doing so: object/relational mapping (O/RM), and tabular access. So to summarize the high-level scope of the guidance:

Direct access to SQL Server
- 1. Use object/relational mapping (ADO.NET Entity Framework)
- 2. Use tabular access (Classic ADO.NET)
No access to SQL Server
- 3. Consuming data services (ADO.NET Data Services, WCF, etc.)

Specifics

We’re going to use 2 forms of guidance to illustrate these 3 primary scenarios:

Reference Implementation (RI). This is a real worldish application that is made up of an ASP.NET MVC web app, a WPF client, and a Silverlight client that each cater to the 3 different roles who use the solution. This RI will only include the O/RM and data services scenario. Tabular access isn’t illustrated since it is better understood. The image below summarizes this online commerce platform.
Written guidance. This book/PDF will have 2 parts.
- Architecture. Technology-agnostic topics and cover important concepts, principles, and framing. These topics will cover all 3 scenarios (O/RM, Tabular, and Data Services).
- Implementation. Technology-specific topics that correlate the architecture topics with how and where they are implemented in the RI.

Engage!

Like all p&p projects, we’re dropping code after each iteration (2 weeks) on the CodePlex community site and are actively soliciting feedback from YOU about what you need and how we’re doing – the more you engage, the better the guidance will be.

So hop over, download the latest drop, and let us know what you think of how we view the world of .NET data access. We’ve set up a specific page for feedback if you’re curious what questions we have – we’ll continue to build on this list over time. We’re looking forward to your feedback!

What's the deal between Devs and DBAs?

donsmith — Wed, 01 Jul 2009 21:42:00 GMT

As part of this Data Access Guidance project I'm workin on (which I'll blog more about soon), we're having a discussion with our advisors about the contention between the influence a Developer has on an enterprise solution and the influence a DBA has on the same solution. Because one of the deliverables of this project will be some written guidance, this seemed like a great opportunity to help each side identify with the other perspective so they both can have maximum impact on the solution. This will likely have a considerable effect on the architecture of the solution too.

I've created a wiki page on the project's CodePlex site so we can capture your experinece. Please pop over and drop us a line. We'll incorporate the comments into the draft over time. Thanks!

Using MessageContracts and DataContracts

donsmith — Tue, 11 Mar 2008 05:10:00 GMT

Users of the Service Factory often ask about the rationale behind the required use of MessageContracts even though the use of MessageContracts aren't mandated by WCF. I've answered this question in other venues, but it seemed like a good thing to put here in case I need to point others to it in the future.

If you ask the WCF product team when you should use a MessageContract versus a DataContract, their guidance usually revolves around the level of control you need over the message - like when you need to use custom SOAP headers*. You can find more detail in this topic of the WCF documentation. Their guidance makes complete sense if you think about the motivation they had when building WCF: to unify all of the Microsoft communication mechanisms into a single approach that is relevant to all scenarios. This is great for someone who has traditionally only done object-oriented or component-oriented development. They can be successful without understanding the nuances of building Web services.

In our experience one of the biggest hurdles for many developers who are new to Web services has been the concept of the message - rather than just passing around types like they've always done. You can characterize this distinction as implicit versus explicit message design. We have a topic in the Service Factory documentation that touches on this distinction. I think there is some room for improvement on this topic, but you can find it here nevertheless.

However, the confusion over a message isn't the only reason we elevate the importance of the message and recommend these usage patterns. We intentionally draw a clear distinction between types (both primitive types like string, and complex types like Customer) and messages (like ProcessExpenseReportRequest). From our perspective, DataContracts represent types and types are reusable. Messages are not used as types but rather the payload a method operates on - and it is not reusable since they are specific to the operation they are passed to and from. This level of distinction provides architects and lead developers a means of achieving better consistency throughout their organization by being more prescriptive about reusability.

I am aware that Juval's position is that MessageContracts are rarely needed. And, I hold Juval in the highest regard - I've not yet had an opportunity to learn what is motivating him to take this position. Some might argue that MessageContracts are just an additional (unnecessary) level of redirection. I can understand this point of view. We just feel the benefits greatly outweigh this nominal cost, and the feedback we've received from customers has been completely supportive of this approach.

* In my opinion, there is only one reason you would need to create a custom SOAP header that isn't already defined by a standards body like WS-*. (hint: if it's already defined elsewhere, you should use it to ensure interoperability, instead of "rolling your own") And, that reason is if you need to pass around localization information (like "en-us"). I don't think this is covered by any WS-* or other spec.

Pretty Impressive Management

donsmith — Mon, 25 Feb 2008 08:17:00 GMT

I was pretty impressed by something my manager did recently. I've shared it with a few other people, but I think this is noteworthy enough for a blog entry. My hopes are that other mangers will be equally impressed and carry out similar acts.

My manager (we'll call him Shaun ... since that's his name) and I were talking about career development during one of our weekly one-on-ones about 8 months ago and I mentioned to him that I would really like to take on some direct reports and more responsibilities at the group-level (of patterns & practices). I've always enjoyed seeing people succeed and am ready for my job to allow me to have a more direct opportunity to influence that more. I've also been in p&p for almost 3 years now and feel I have a deep understanding of what we do and how we do it.

I really shared this with him so he would know what I was thinking - not because I expected him to do anything about it. Actually, I didn't think he could do anything about it. You see, p&p is a small group - only about 30 full-time Microsoft employees. In other words, there is no way for me to move up and stay in p&p unless another manager slot opens up, which isn't likely, or Shaun leaves his position, which I also didn't think was likely. Shaun was basically the second employee of p&p - he and Mike Kropp founded the group.

Of course Shaun also knew there wasn't anywhere for me to go if I wanted to stay in the group (which he knew I absolutely wanted to do). Imagine my surprise when I found out that it was around this time that he began looking for other opportunities outside of p&p. Fast forward to today. Shaun has found a very challenging role in another group in Microsoft and has named me acting* Senior Product Planner. After this week, I will be honored to have Glenn, and Grigori reporting to me and I'll have to hire my replacement (let me know if you're interested).

When he told me that it was my desire to move up that caused him to reevaluate his situation, I was more than impressed. Yes, Shaun has been a fantastic manager (Glenn and Grigori agree) and it is this kind of act that speaks volumes about the kind of person and manager he is. I'm not so naive to think that my desires are the only thing that motivated him to move on, but knowing it was a factor is impressive enough. It's very different from the "yeah, I'll get to move up when Joey Stayput dies" situation we always hear about.

Thank you Shaun. I have some great shoes to fill and I promise do my best.

* Right now p&p doesn't have a leader. Once one is appointed (hopefully in the next 2 weeks) he will decide if I take on the role completely or if he would rather hire someone else into it. So until then, I'm just "acting".

Roger joins the fray ... w00t!

donsmith — Wed, 13 Feb 2008 20:32:00 GMT

My good friend Roger Lamb has just joined the blogsphere and I assure you that if you are interested in anything remotely related to Sharepoint, you'll want to subscribe now. Check out his first post.

You see how I just did that? How I increased your expectation, and thus, his commitment around his blog?

Isn't the blogsphere wonderful? haha

Welcome to the chaos bro!

Influence MSF guidance

donsmith — Thu, 27 Sep 2007 19:27:00 GMT

My colleague, Andrew Delin, is making the process of developing software real for development teams. However, he doesn't want to do it in a vacuum. If you think you know anything about development processes, I'm sure he'd love to hear from you. http://blogs.msdn.com/processblog/archive/2007/09/25/so-tell-us-what-you-think-about-the-msf-guidance.aspx. Thanks.

A time for reflection and assessment

donsmith — Tue, 08 May 2007 09:15:00 GMT

Wow, it's hard to believe it has been almost a year since the patterns & practices team released our first software factories. Remember when the early customer previews were called Baseline Architecture Toolkits? Oh, the nostalgia :) We could have had so much fun with the BAT acronym ... haha.

So that means now is a perfect time to take a quick assessment on how we're doing so far ... that's right, a survey. Now hold on a second! At least hear me out for the rest of the paragraph. I can't devulge too much detail yet, but some team in Microsoft might be in the middle of building some serious software factory infrastructure for a future version of Visual Studio - that's right, much better than GAX and DSL tools. Do you want it to suck? Do you think software factories are just a pipe dream and would rather they build something else? If you're thinking, "Oh no Don, I like software factories, especially the Service Factory (okay, I'm embellishing - haha)," then I would ask you to keep reading. I promise we've tried to optimize the survey to allow you the highest level of impact in the least amount of time possible.

Whew, you're still reading ... excellent! Okay, so you're only looking at 9 generic questions and 9 questions for each software factory you've evaluated/used. This survey covers the 4 factories released by p&p (web service, smart client, web client, and mobile client). The first 8 questions will take no more than a minute or two. The 9 questions for each factory shouldn't take more than 10 minutes each and you will only see the questions for the factories you choose. The last question is an anything-else-you-want-to-share question - you can take as long as you want on it. That's it ... super quick-n-easy.

Here is the URL you need to take the survey: http://www.zoomerang.com/survey.zgi?p=WEB2266YYVWSKP

We're really looking forward to your feedback so we can help the future include some truly kick-ass factories.

First Service Factory v3 Community Drop

donsmith — Sat, 07 Apr 2007 09:28:00 GMT

Okay, we're off and running now. Earlier today I posted the first of many community drops for Service Factory v3 - don't let "build 19" fool you - this is the first one. It took us longer than expected to get this one out the door, but we're all set now.

I suspect the first question you have is "What is so specially about this release?" Fair enough question. Well, probably the biggest thing is the addition of models. This alone accounts for most of the improvements over v2. I'm not going to go into too much detail here (there will be plenty of time for that later), but here are the high points:

Now Visual Studio has a memory about your decisions. In v2 you place your decisions in wizards. In addition to models, there are still wizards, but it's the model that "remembers" so you can generate code anytime you like.
Now you have a visualization of the application you are building. The designers provide this. Right now there are 2 designers/models. The first screen shot below shows the one for service contracts and the one after that shows data contracts.
Now you can delay the platform decision (WCF/ASMX/etc) and the language decision (C#/VB/etc) until as late as you like (way after you define all the service, message, and data interfaces.
With this version there is also no assumption that you have already define the service contract before you start using the factory. You can either approach the solution from a capability perspective (dropping operations on the service contract designer) or from a data perspective (dropping data contracts on its designer).

Here is what they look like (I added the thin red boxes):

I'm trying something new during this release by including a "start here" document and a "walkthrough" document for each drop. I'm hoping this will:

Save you lots of time in evaluating this drop.
Set your expectations around how much time you will need to evaluate the drops.
Provide you a very directed way to provide feedback about the drop.
Give you an easy way to see what the new features are every 2 weeks.
Let you know what the known issues are with each drop.
Get me more high quality feedback so I'll know we're building the best, most appropriate Service Factory we can for you.

So please use these docments and give me your thoughts about them.

You can expect new community drop every other Friday until the end of October (unless something really unexpected happens of course).

Download Service Factory v3 Community Drop 19 here

Looking forward to your feedback ...

Now Available: Aaron's new Service Factory article on MSDN

donsmith — Thu, 11 Jan 2007 11:04:00 GMT

Steven just told me that Aaron Skonnard's latest Service Factory article about the December release was just published through his Service Station column in the MSDN Magazine. Talk about timing ... sweet.

Even though it was written and finished before we locked down the code, it is still very accurate and comprehensive. I mean, it's Aaron ... what else would you expect?! There a few minor places where we changed the code out from under him so if you have a question about anything in it, feel free to leave a comment here and I'll field it.

Oh, and if you're building ASMX services, be sure to check out his first Service Factory article about the July (ASMX) release.

Great job Aaron!

... come and get yer Service Factory!

donsmith — Wed, 10 Jan 2007 07:30:00 GMT

That's right ladies and gentlemen, the December release of the Web Service Software Factory and a VB.NET version is now available for your consumption, modification, and production pleasures :)

Okay, I'm just going to do 3 things in this post since I know there will be many more to follow:

Lay some links on ya. For downloading the Service Factory releases and more info.
Share my favorite new features of the Service Factory with you.
Give you a sense of what is to come in the near and not-so-near future.

Links

Service Factory December release helps you build both WCF and ASMX services in C#. The old July release is no longer available since everything it contained is included in this release. Web Service Software Factory–December 2006 (ASP.NET and WCF services in C#)
Service Factory July release that helps you build ASMX services in VB.NET. Yes, I know this is new and was actually published in December, but it is effectively the same exact version as the original July release - it's just been converted to VB.NET (that's why we're calling it the July release). If this is confusing, I apologize ... I'm to blame. Web Service Software Factory–July 2006 (ASP.NET services in VB.NET)
Service Factory information. If you're not sure what the Service Factory is and want to find out before downloading it, go to http://msdn.com/servicefactory to learn more about it.

Favs

WSDL-first support. This feature definitely wasn't the most challenging to include, but I still love it. I've spent a lot of time over the years monkeying around with WSDL files. The fact that Service Factory has a single recipe (wizard) that will take a single WSDL and generate the service interface, service implementation, binding configuration (config file), and all of the associated DataContracts/XmlSerializable types is just freakin' sweet. You have to see it even if you don't define all your contracts in WSDL first.

Versioning guidance. This is a favorite of mine because ... well, I wrote it haha. No, seriously ... it's no secret this is a topic that is near and dear to my heart. I have labeled the topic "emerging guidance" in the Service Factory documentation because I want to gather more evidence from customers that this approach is actually working for them before I propose we call it a "proven practice". I have spoken with a number of customers who have taken this approach and it is working well for them. I haven't spoken to anyone it didn't work for, but I'd love to hear from you. If you're interested in reading or sharing, I've also posted the topic on my blog here. Personally, I think the "strategy" section of the guidance is still weak on content, but more on that in the "futures" section of this post. I also plan to do a webcast on it.

WCF Code analysis. This one turned out to be the sleeper feature - we didn't expect this to turn out so sweet. As you may know, FxCop has been integrated into Visual Studio 2005 under the name Code Analysis. Well, we took all of the same rules that used to be the Security Analyzer back in the WSE days and converted them all to code analysis rules. They also work against the code AND the config files (something FxCop hasn't done historically). I know, pretty sweet, huh? Well, when we showed this to the WCF team, they asked if we could include some of the rules that they fire at run-time so they could be run at design-time (like the ones that make sure all the binding stuff is consistent). "Sure", we said. So there are about a dozen of them too ... and it's all integrated into Visual Studio ... even if you're not using Service Factory.

Recipe runner. Okay, now I'm cheating a little. This isn't actually a feature ... and it's not really included in Service Factory. One thing we learned while building the July release was that testing GAX recipes is feakin' hard. Well, harder than it should be. So the team took a couple of months at the beginning of this version to get it right. The result is something we call RecipeRunner. Those of you who are creating your own recipes or heavily modifying the ones we provide will really like this if you care about testing, which you should. We'll be making it available on the community site in the near future.

There are loads more things that are new and way cool in this release, but I want you to discover some of them for yourself too. Of course I'll be mentioning them as time goes on and in some mini videos. Oh, that brings me to the last item on my agenda.

Futures

Blogcasts. The very next things you're going to start seeing are more of the blogcasts I did some months back. Many of them are outdated now and I need to do more of them now that the WCF Service Factory has released. The feedback was very positive (thank you) and because I claim to listen to you, I promise to do more of them shortly.

HOL exercises. I've already began the process of converting the existing hands-on lab (HOL) to WCF. Additionally, we'll be adding a bunch of new exercises. What I need from you is some details so we're sure they are helpful. This is what we have in mind:

Modifying a guidance package - There is already a how-to in the Service Factory documentation, but customers are always telling me they need more help. If you tell me what kind of changes you're making to guidance packages I will try to create an exercise that illustrates how to make that change.
Building a service agent - A service agent is that layer of code on the consumer side that invokes the proxy (that's right, you're NOT suppose to do it in the button's click event handler :). It manages things like retries, response caching, offline support, asynchronicity, etc. I need you to tell me what kind of challenges YOU (not your neighbor) need. That will help me get this exercise right.
Versioning - this will build on the topic I mentioned earlier and will walk you through how to evolve a service in a number of ways.
Message validation - The reference implementation already illustrates this. But would you find a HOL exercise valuable? If not, cool, I'll spend that energy somewhere else. If so, also cool.
Exception shielding - The reference implementation also illustrates this. Same question ...
Create a code analysis rule - I think this is also covered in the VS documentation, but I've never looked for it. Are you going to be writing your own rules? If so, would you find a HOL exercise helpful?
Workflow Foundation - we actually did a lot of work with this, but had to pull it at the last minute (yeah, sometimes cutting scope at the last minute hurts). We might be in a position to create an exercise as a result of what we already have. We'll see.

v3 planning. We have already began the planning process for v3. But because we JUST started, we don't have a lot to share just yet. I can tell you (if you didn't already guess) that a service domain specific language (DSL) is the primary theme of the next version. I will be sharing everything with you around the features and their priorities as soon as we have something to share. As always, we'll be counting on you to steer us where you need us to go. All of this communication will naturally happen on the Service Factory community site, which will be moving to CodePlex in the very near future. More on that later too.

Okay, it's getting late and the weather is getting nasty so I'm heading home. Until next time, you have a lot to keep you busy :D Looking forward to your feedback. Thanks!

Handcrafting WCF-friendly WSDLs

donsmith — Fri, 06 Oct 2006 10:30:00 GMT

It's 10:15 pm and I'm still in the office, but I really think I should get this entry posted before I head home - or it won't ever get posted. I was supposed to be working on my demo for my Service Factory session at the SOA Conference tomorrow, but I got side-tracked early in the day when I started playing with a new feature of Service Factory (that I'm going to demo). This new recipe (hereforth referred to as "the new recipe") allows you to create the service interface, data contracts, and a stub of the service implementation from an existing WSDL document. Yeah, pretty cool, huh? Of course you can do the same thing in svcutil if you have the .NET 3.0 SDK installed, but you have to leave Visual Studio and head off to the command prompt - and it won't separate the parts into multiple files and place them in the appropriate projects.

As I'm sure you've already realized, we've added this feature for the masses who have adopted a contract-first approach to building services. Unfortunately for these masses, the object model you have to code against after you've generated code from your existing WSDLs (using either svcutil or the new recipe) is not as enjoyable as what you get with the code-first approach WCF and its DataContract offer. I'm hoping this entry will add some clarity for those of you who wish to have the best of both worlds: Contract-First and DataContracts. First, let's talk about the DataContract.

The DataContract

Rather than start from ground zero with DataContract basics and the DataContractSerializer, I'm going to recommend you go read Aaron Skonnard's excellent Service Station article on Serialization in WCF before continuing. Okay, now that you know DataContract only supports a subset of XML Schema, let's get more specific about this "subset". I am in no way stating that this is a complete list, but these are the things I've personally been able to verify. If you use any of the following constructs, svcutil and the new recipe will fall back to creating XML serializable types (like the ones in ASMX) instead of DataContracts.

<xs:element ref= ...
<xs:anyAttribute ...
<xs:group ref= ...
<xs:attribute ...
<xs:choice ...
<xs:any ...
<xs:all ...

Of course this pretty much means to be safe, you need to stick with a <xs:sequence> of <xs:elements>. However, I was a little surprised to see that a <xs:simpleType> <xs:restriction> on a xs:string generated a very nice enum. Oh, News Flash! Kirill just responded to my email (hey, what's he doing on email this late?) and pointed me to some [internal] beta documentation that very clearly defines how all XSD constructs map to DataContracts. The doc looks awesome - I'll be sure to update this entry once it is live on the Web (if I don't, remind me). Okay, but you're not in the clear yet. You see, now we have to navigate the message wrapping issue.

The MessageContract

Because the DataContract is all about simplifying interop and the object model (OM), it hides wrapping element from the code, but (obviously) not from the WSDL. So, if you're going to import your handcrafted WSDLs, you need to know how to represent the wrapper "message" in WSDL in such a way that you don't have to deal with them in your OM. I think the easiest way to explain this part would be to start with a fragment of a WSDL and show what must change to get the right stuff in code. Consider this:

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  xmlns:srvc="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
                  xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
                  targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<wsdl:types>
    <xs:schema elementFormDefault="qualified"
                   targetNamespace="http://MyOrg.HrSrvc.DataContracts/2006/10"
                   xmlns:tns="http://MyOrg.HrSrvc.DataContracts/2006/10">
      <xs:element name="Employee" type="tns:Employee"/>
      <xs:complexType name="Employee">
        <xs:sequence>
          <xs:element name="ID" type="xs:int"/>
          <xs:element name="Name" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>
</wsdl:types>

<wsdl:message name="AddEmployeeSoapIn">
    <wsdl:part name="request" element="data:Employee" />
</wsdl:message>
<wsdl:message name="AddEmployeeSoapOut">
    <wsdl:part name="response" element="data:Employee" />
</wsdl:message>

<wsdl:portType name="IEmployeeManager">
    <wsdl:operation name="AddEmployee">
      <wsdl:input message="srvc:AddEmployeeSoapIn" />
      <wsdl:output message="srvc:AddEmployeeSoapOut" />
    </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="YouGetTheIdea"/>
</wsdl:definitions>

Yes, I know I'm sending and receiving the same type. I'm trying to balance between brevity and reality (cut me some slack). Hopefully at this point I have some contract-first readers nodding their head thinking, "Ok, I'll buy that - seems reasonable enough." Now let's look at how we would have to write this to get the nice dev experience with WCF ('cause this won't create it).

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:srvc="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<wsdl:types>
<xs:schema elementFormDefault="qualified"
   targetNamespace="http://MyOrg.HrSrvc.DataContracts/2006/10"
   xmlns:tns="http://MyOrg.HrSrvc.DataContracts/2006/10">
<xs:element name="Employee" type="tns:Employee"/>
<xs:complexType name="Employee">
<xs:sequence>
<xs:element name="ID" type="xs:int" nillable="true"/>
<xs:element name="Name" type="xs:string" nillable="true"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
<xs:schema elementFormDefault="qualified"
   targetNamespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10"
   xmlns:data="http://MyOrg.HrSrvc.DataContracts/2006/10"
   xmlns:tns="http://MyOrg.HrSrvc.SrvcContracts/2006/10">
<xs:import namespace="http://MyOrg.HrSrvc.DataContracts/2006/10"/>
<xs:element name="AddEmployee"/>
<xs:complexType>
<xs:sequence>
<xs:element name="request" type="data:Employee"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="AddEmployeeResponse"/>
<xs:complexType>
<xs:sequence>
<xs:element name="AddEmployeeResult" type="data:Employee"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>

<wsdl:message name="AddEmployeeSoapIn">
<wsdl:part name="parameters" element="srvc:AddEmployee" />
</wsdl:message>
<wsdl:message name="AddEmployeeSoapOut">
<wsdl:part name="parameters" element="srvc:AddEmployeeResponse" />
</wsdl:message>

<wsdl:portType name="IEmployeeManager">
<wsdl:operation name="AddEmployee">
<wsdl:input message="srvc:AddEmployeeSoapIn" />
<wsdl:output message="srvc:AddEmployeeSoapOut" />
</wsdl:operation>
</wsdl:portType>

<wsdl:binding name="YouGetTheIdea"/>
</wsdl:definitions>

The highlighted areas are the parts I added/changed from the first snippet. It’s after midnight now. I’ve learned the beta of Windows Live Writer I was using has a length limitation and doesn’t color XML snippets (yes, I did this manually for your reading pleasure). So rather than continue to wow you with my use of compelling prose, I’ll just bulletize (see?) the significant parts:

· What’s up with the nillable=”true” on the data types? That actually turns out to be pretty critical. I haven’t really thought to much about why yet, but without this construct, it complicates the OM bigtime.

· What about that new schema … doesn’t that complicate the OM? Surprisingly not! It won’t even show up in the generated code. Notice how it imports the existing schema to reference the existing types, which do show up in the code. If you don’t explicitly create this wrapper, it will think the first element it finds (Employee otherwise) is the wrapper … yuck.

· Can the wrapper elements (AddEmployee & AddEmployeeResponse) be in the same namespace as the data type (Employee)? Well, that depends. They can if that namespace just happens to be the same as the service. In other words, the wrapper schema has to share the same namespace as the service. It doesn’t matter if the data types are in the same namespace or not.

· Don, is the fact you named the wrapper elements “AddEmployee” and “AddEmployeeResponse” important? Yes. If you don’t follow this convention, you’ll see these as types in the code … yuck!

· Let me guess, it’s also important that I name the data:Employee elements “request” and “AddEmployeeResult” respectively? Well, not really so much. If you name them something else, like “RequestMessage” and “ResponseMessage,” the System.ServiceModel.MessageParameterAttribute will step in to make sure the response message is correct on the wire, but it won’t affect the OM so much. It will look like this:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]

[ServiceContract(Namespace="http://MyOrg.HrSrvc.SrvcContracts/2006/10"]

public interface IEmployeeManager

{

[OperationContract(Action="...", ReplyAction="*")]

[return: MessageParameter(Name="ResponseMessage")]

Employee AddEmployee(Employee RequestMessage);

}

· Alright, what’s up with the “parameter” message part names? Yeah, that’s important too. That basically says this contract is wrapped and not bare.

I think that’s about it. I’ll update this entry if I think (or learn) of anything else, but I’m going home now. Hope you find this helpful. BTW, I was listening to the Lemonheads the entire time I was putting this together … pretty cool.

Written Guidance. Necessary?

donsmith — Sun, 03 Sep 2006 10:40:30 GMT

In my last post I mentioned that we are having a lot of hallway discussions lately. Another topic that is getting a lot of airtime lately is written guidance. As you know, the patterns & practices team has been producing written guidance since the team was created. Over the years we've evolved the the code-based guidance considerably - from reference implementations and application blocks to software factories that contain guidance package (code generation), the written guidance has pretty much stayed the same. This may or may not be a problem, but there inlies the problem - we don't know. We actually get VERY LITTLE feedback on written guidance. That could mean one of a few things: it is perfect and can't be improved, no one is reading it, or no one cares. If it has no need for improvement, great, but I find that hard to believe. If no one is reading it or doesn't care, THAT is a problem. We invest a lot resources into the parts of the deliverables you can read and print. If those resources can be repurposed - that would be a good thing to know. I would love for you all to educate me with some comments. Feel free to use the questions as examples of the things we're interested in. Thanks!

If you've downloaded any of the factories, did you read any of the written guidance?
If so, when did you read it? before doing anything else? only when you ran into a problem? when you were interested in the rationale behind the guidance?
Did you find what you were looking for? What is your impression of the overall quality?
What are the most important sections (how-tos, patterns, explained, etc)?
Should we continue to make investments in written guidance? should we increase or cut back?

It's all about community!

donsmith — Sat, 02 Sep 2006 13:26:14 GMT

There have been a lot of hallway conversations on the p&p team lately and the state of our community infrastructure is one of the popular subjects. Customer feedback influences our guidance more than anything else ... period ... and since our communities are one of the primary ways we interact with customers, you can imagine how important it is to us that they be happy with the experience.

GotDotNet, as it exists today, is not a long-term solution. By the end of the fiscal year, I will have a plan in place to transition off of it and on to ... well, that still remains to be decided. These hallway conversations have been about how we can improve the community experience. Unfortunately, we don't have a very good understanding of how our customers WANT to interact with us - seems strange to hear that, huh? So right now I'm drafting a document that lists all of the capabilities (stacked and ranked) we feel are necessary for our community infrastructure to have - independent of anything that may already exists.

I fully intend on making this document publically available, but first, we would really like to know how YOU would like to interact with it. First, think about the communities you've seen and use today: gotdotnet.com, channel9.msdn.com, codeplex.com, forums.microsoft.com, sourceforge.net, netfx3.com, blogs, etc. Think about the things you like, and don't like. Think about the things you use and don't use. Feel free to read the following questions to stimulate some brainstorming even though it is a far-from-comprehensive list.

Membership

What are your thoughts about "joining" a site?
What do you prefer for member credentials (username/password, hotmail/passport account, other)?
What is needed as far as roles go (owner, contributor, member, anonymous)?

Release Management

How do you want to get new drops (zip, exe, msi)?
Do you want a source code tree to sync with?
What is the right frequency for releases (weekly, forthnightly, monthly)?
What is the right quality bar for releases (just builds, no exceptions, very stable)?
How far back do you want to be able to go? Realistically?

Issue Tracking

Do you want to be able to submit bugs? And track them (priority, status, etc.)? How?
What kind of queries do you want to run against the bug database?
What would you use the issue tracking feature for?

Two-way Communication

Is a forum (message board) the most appropriate mechanism? If not, what is?
What features are needed (sticky posts, creator control, post popping, quoting, etc.)?
What metrics are you most interested in (e.g. number of [unread/answered] posts)?
How do you want to provide feedback to the team?

One-way Communication

Is wiki the most appropriate mechanism? If not, what is?
Will you edit pages (like written guidance) if given the choice?
Would you contribute new topics if given the opportunity?
How can the team communicate to you more effectively?

Like I said, this is FAR from comprehensive, but hopefully it generated some sparks. I can tell you that any direction you can give us will influence our decisions in a big way. Think of what the perfect community site would let you do - and let us know. Thanks!

WCF Guidance Packages now available for consumption

donsmith — Thu, 31 Aug 2006 19:21:56 GMT

If you've been following the Service Factory project, you'll know that we had to put the WCF guidance on hold for a little while as we were getting the ASMX Service Factory released. Well ever since it was released, we've been working on getting caught up on the WCF guidance. This actually took longer than expected because in addition to making the WCF Feb CTP -> July CTP changes we felt the need to fix a bunch of the bugs we identified in the similar ASMX GPs so now there is some fidelity between the two.

Is this release of the Service Factory going to go down like the last one? You know, that is a great question. If you mean, "Are you going to release regularly to the community?" and "Are you going to solicit as much feedback from us as possible?" the answer is absolutely yes! As a matter of fact, we're even trying to improve.

Drops will be more regular and predictable - monthly to be exact and at the end of the month to be specific
We're separating the documentation drops from the code drops. They will also be released monthly [in CHM format] ... they will just be 2 weeks after the code drops
I've changed the way we're making the known issues available. Rather than putting some of them in the readme file, now you can find all of them in an Excel spreadsheet. Just Ctrl-F the issue you're looking for.

As always, I'm interested to know what you think about these changes. What would make is easier to follow this project?

Side note: I think it's still a little strange for some people to realize the impact they can have on a team, like patterns & practices, where "customer connected engineering" is the basis for everything they do, how they do it, and what they deliver. There aren't too many teams [even in Microsoft] that are applying this amount of feedback from their customers.

Anyway, check it out and let us know what you think. We're listening.