| Comments

If your a developer that spends any time with web services, you’ll basically probably end up working in one of two camps: REST- or SOAP-based services.  Now with SOAP services you’re likely used to having a WSDL document describing the service, providing type definitions, etc. – something you can use developer tools like Visual Studio to Add Service Reference and get a strongly-typed object model to work with.

If you’ve been doing Silverlight or ASP.NET (or any other technology really) development with mashup services, you probably have been working with REST-based services.  These are services that don’t self-describe themselves in a manner like SOAP with WSDL does.  Often I’ve found that really only the larger REST service providers provide good documentation for their services.  As a consumer of a REST service, you’re at the mercy of the documentation to understand the structure of the requests/responses that you’ll be working with…at times that can be frustrating.  If you are like me, you’ve probably either found someone else’s wrapper to the API or tried to work some other method to avoid spelunking the XML nodes.

If you don’t need to take on the full wrapper that you may have found someone already doing and maybe just need to consume something quick or whatever, enter Paste XML as Types.  Located in the WCF REST Starter Kit Preview 2, this is a Visual Studio new option under the Edit menu.  Let’s take a look at an example.

Twitter sounds like it would be a good example, but honestly they provide so many different formats (JSON, XML, RSS) that I’m not sure you would really want the XML version when RSS is more of a known type and easy to work with.  So let’s look at the Flickr API which is a similarly popular one and has a well-documented REST interface.  Let’s say you wanted to work with the results of their ‘interestingness’ public query which will provide you with a list of photos.  We can see in their documentation that they provide us with a sample response:

   1: <photos page="2" pages="89" perpage="10" total="881">
   2:     <photo id="2636" owner="[email protected]" 
   3:         secret="a123456" server="2" title="test_04"
   4:         ispublic="1" isfriend="0" isfamily="0" />
   5:     <photo id="2635" owner="[email protected]"
   6:         secret="b123456" server="2" title="test_03"
   7:         ispublic="0" isfriend="1" isfamily="1" />
   8: </photos>

Sweet.  Copy that sample response.  Go into Visual Studio in your project class file (or create a new one), go to the edit menu:

Paste XML as Types

Booyah!  Watch as the magic happens and the XML structure is transformed into strong types for you.

Well, sorta.  Turns out while I think this is a cool feature, it might have some work still to go.  My first assumption was that the documentation on Flickr matched exactly the response (heck, it says sample response).  But it really is only the response body.  There was some missing response header nodes.  You should call the API directly to see a real response.  Second, even with that it looks like I’m getting some weird namespace stuff.

But regardless of that, even taking an XML file and being able to reflect on that to create an object model on paste is pretty cool. 

Try this out – if you see issues leave comments on the WCF REST Starter Kit site so they can see them – you’re welcome to leave them here as well, but I’m not on that team and it’s better to give direct feedback on their project.

| Comments

FeedReader is a web part for Microsoft SharePoint server products (MOSS and WSS).  It’s purpose is to aggregate more than one feed in a single web part.  The built-in XML and RSS web parts for SharePoint only allow one feed by default.  feedreader can support Atom or RSS feeds.  Please report any issues as a Work Item on the project.  Source code is also available on the project site under a very permissive license.

Thanks for using feedreader!

This work is licensed under a Creative Commons Attribution By license.

| Comments

When working with data and Silverlight there has often been the questions of wondering why when a service call fails that Silverlight returns the HTTP 404 status code.  In fact I’ve written about troubleshooting those types of issues in the past and tools you can use to help investigate some problems.

Still people mostly ask "if there is an exception, why is Silverlight telling me ‘not found’ instead of sending me the exception?'”  Eugene Osovetsky from the connected systems team aims to answer those questions in a recent post with a little more detail than has been provided in the past as well as offering some suggestions.  From his post, this is one of the main reasons which I’ve echoed in discussions, webcasts, forums in the past as well:

“Unfortunately, web browsers have a limitation with regards to status codes: When a browser plugin (such as Silverlight) makes an HTTP request, and the response status code is not 200, the browser hides the actual status code and the message body from the plugin. All Silverlight knows is that "something went wrong", but it has no way of discovering any details.”

Take a look at Eugene’s post for some other helpful suggestions.

| Comments

If you are starting to get into integrating web services with Silverlight, you'll notice that you have to have a cross domain policy file in place on the target server, that is to say, the server hosting the service you want to implement.  There are some public web services (Flickr, YouTube, Digg, etc.) that already have these files in place for Flash, but implement in a slightly different way.

When calling a cross-domain service, Silverlight will check for the existence of clientaccesspolicy.xml first.  This is the format defined by Silverlight and provides a pretty flexible way to define who can access what services.  If not found, it will then default to look for crossdomain.xml, which is the file format implemented for Adobe Flash.  It is important to note that this file will also still work for most public web services.

But now perhaps you are the author of the service that your application is going to consume and/or the public will consume.  There are a few things you want to consider.  First, it would be a best practice to put your service layer on a separate domain other than your site (i.e., api.mysite.com).  In fact, this is how most are doing it these days.  These helps separate more distinctly the services from the web site and also separates the cross-domain security concerns away from the content site versus API access.  Once you have done that you'll want to implement your specific clientaccesspolicy.xml file.

When Silverlight 2 was released to beta, I created some quick helper files to assist me with creating this simple policy file (it is simple, but can get complex depending on how granular you want to define your access).  I figured it might be helpful to some who are implementing services as well.  Sure, they aren't going to save the world, but might save you some quick typing.

Visual Studio Code Snippet

The slcap.vsi file is a Visual Studio Community Installer package which contains "slcap.snippet," which is a Visual Studio code snippet format.  This is an XML snippet, so would be used only in the context of an XML file.  Just double-click on the .vsi file to install and it will walk you through the steps.  I recommend just keeping the defaults.  After it is complete, you now have an Intellisense snippet.  To use it and create a new clientaccesspolicy.xml add a new XML file to your web service site/project named clientaccesspolicy.xml.  It will open a blank XML file by default.  Select all text (CTRL+A).  Then hit the keyboard shortcut for launching XML snippets, CTRL+K,X.

NOTE: For some reason XML snippets don't operate like C#/VB ones do where you type the shortcut, then TAB, TAB.  If anyone knows why, let me know :-)

This will bring up the navigator, then simply navigate to the My XML Snippets, then locate the one you just installed:

Once you select it, there are three literal areas to override the defaults if you wanted. 

UPDATE: As Sean probably ran into below (in comments), the above screenshot does not show the required http-request-headers attribute required on the allow-from node of the policy file.  This is, however, updated in the Intellisense files and the code snippet template.  Thanks Sean for pointing out the screenshot is wrong here.

If you are implementing a completely public web service (open to anyone for cross-domain access), then the defaults will suffice.  When done changing the values, hit enter and you are done.  For those who are not keyboard shortcut masters and would be using a mouse to do all this, it might not be terribly faster to be honest (if the TAB,TAB implementation was there for XML snippets, it would eliminate the arrow up/down to navigate to the snippet).

Get the slcap.snippet here.

Visual Studio Intellisense Files

This next step is a super hack that I originally did and decided it might not be a good idea, but I'll include it here anyway :-).  This involves adding Intellisense files to your VS2008 installation and if you aren't comfortable with that, then move along.

First, you'll want to get the XSD I created, which is very simple and I'm sure doesn't fully conform to the final spec, but lacking that spec, it maps to the format well enough.  Copy the clientaccess.xsd file to the C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas location (or wherever VS2008 is installed for you).  Once you've done that you have to add an entry into the catalog.xml file to add the mapping.  Again, not this is my little hack so I created some namespace because there wasn't one defined yet.

Once you have those two files you have Intellisense for your clientaccesspolicy.xml file if you want it.  Following similar steps as above, create the new file.  This time, however, type the root node of <access-policy> but adding the 'xmlns' attribute pointing to the new namespace you just added to the catalog file (note: Intellisense should give you a list to choose from:

Once you have that, then you'll get the rest of the Intellisense for the basic format of the client access policy format.  If you have multiple allow-from/grant-to needs, this Intellisense will support it.

The only lame thing is you have my namespace in there :-).  That is what drives the Intellisense.  Right now you'll want to remove that before deploying the actual file.  Yeah, I know.  But I said this was an early hack of mine didn't I?

Get the Intellisense files here.

What do to with the completed policy file?

Either way, when you are done with the file, it needs to go in the ROOT of the domain.  This is important as it is not the application root, but the root web.  Even if your app is at foo.com/myapp, the policy file needs to be at foo.com/clientaccesspolicy.xml.

Anyhow, maybe these files will help you.  Ideally you won't be using/messing with an access policy file much, but this might save you some clicks and having the docs open next to you :-).

| Comments

thanks to all who came out to the denver devdays big event this week.  this was the first time i've traveled in a while since various family ailments and situations.  i had a good few days in denver with some good peeps.  thanks to beth massi for joining our developer crowd in denver.  she was awesome and had a crowd wherever she was.

i attempted to do justice to office development in one of the sessions.  one of the challenges on that topic is that 'office' now encompasses a lot of things...here's my known short list:

    • word, excel, access, outlook, onenote, infopath, powerpoint
    • smart tags
    • sharepoint
    • communicator
    • excel server
    • workflow
    • groove

so when you have an hour for a developer session, which do you pick.  i chose to pick the office client applications and demonstrate how visual studio 2008 enables writing office client applications easier than ever.  i chose this because doing office client development in the past (even with 2005) wasn't really a no-brainer.  there were still a lot of configurations as well as still some things you couldn't do.  with office 2007 and vs2008, it is a no-brainer now.  vs2008 (professional+) now comes with the office tools built-in...no more needing to download a separate client (or pay for a separate tool).

in my session i attempted to cover four key areas (only three of which we got to).  i wanted to demonstrate the UI customization features, outlook form regions, word content controls and task/action pane development.  the slides for my presentation are at the end of this post (PPT 2007 and PDF) and as promised there is an appendix in there with some information we didn't get to.  the two most important links in the slides are the ones to the Office MsoId sheet and the OfficeImageId worksheet (which you need the developer options to be enabled in Excel to see the gallery options).  get these files.  download.  save.  you'll need them.  and when you can't find them you'll need a mt. dew (or scotch or whatever your calming choice is).  don't ask me why the MsoId's are not enabled in the designers of the office components...i've asked and don't know.

the first thing we covered was the office ui customization.  vs2008 provides a new visual designer for the ribbon.  you can still do the RibbonXML if you're insane you want to.  as we demonstrated, almost everything can be accomplished in the ribbon designer.  intercepting commands (such as FileSave) is something you'd need to much with the RibbonXML for and the designer provides an 'export to ribbon xml' feature so you can do most of it visually.  vs2008 provides a great design-time experience as it provides a ribbon as the design-time experience.  most everything after that is choosing which tab (custom or built-in using one of the idMso values from the worksheet), and adding controls.

this capability enables a rapid development timeline of creating customized ui features that are familiar to your users and integrate with your own application.  i demonstrated my flickr add-in which i install on the TabInsert area of office applications:

in outlook development, vs2008 has made this easier now.  we can now extend the default outlook message class UI implementations (i.e., IPM.Contact, IPM.Appointment, etc.) through designers in visual studio.  the tool enables us to choose how we want our customizations to be as well (replacements, adjoining, etc.).  the image below is the adjoining one we created with integrating virtual earth into the contact form to pinpoint in the contact form the address of the selected contact:

when writing outlook form regions (and as we saw in all other areas as well), the development isn't 'office-ish' at all.  once you've decided where/how the form region is going to interact, now you are just writing managed code.  you can integrate with wcf services, use linq, whatever...it is the same .net framework you know and love.  the office api's are now exposed to you to interact with as well.  as an example, anything in the contact item is easily and readily accessible to the developer to use and/or alter.  the same goes for word, excel, etc.

the last area was the task/action panes.  to clarify the terms:

    • task pane: an implementation of a pane that is application-wide -- every document will be able to use the pane
    • actions pane: document-specific panes that are a part of a document/template but not installed as add-in to the global

the distinction between these two is pretty much at that level above.  there are some subtle differences, but for the most part that is the major difference you need to know.  the panes are implemented as user controls for your app/doc add-in now.  so as a developer you now have a user control surface where you can add controls, interact with the document to get values, etc.  to add your custom pane you would write code like this (using excel as an example and a task pane):

private void ThisAddIn_Startup(object sender, System.EventArgs e)
      CustomTaskPane ctp = this.CustomTaskPanes.Add(new UserControl1(), "Pane Title");
      ctp.Visible = true;
      ctp.Width = 250;

the UserControl1 would be whatever your user control representing the task pane you want to display.  remember, that each add-in has that "ThisAddIn" stub generated for you.  there can be multiple task panes for an app/document.  so if you need more you can go nuts.  but i'd be sure you take into account the user experience and ensure that you aren't crowding the main focus of the functionality (the document) for the user.  panes are dockable through the DockPosition property.  if i wanted my pane to be docked on the bottom i could use:

ctp.DockPosition = Microsoft.Office.Core.MsoCTPDockPosition.msoCTPDockPositionBottom;

but one thing to keep in mind is other properties.  for example, if i added the line above to my initial code and had the width property, i'd get an exception.  i'm trying to set a width when a bottom-docked item fills the user's width -- no can do.  of course i should probably implement better checking and simply handle that scenario.

the action panes are no different (other than how they are added is via a different class instead of CustomTaskPane) and simply are scoped to the document.  both are implemented as user controls and you can put windows controls on there and interact in code however you want.  in fact we demonstrated how we could implement XAML into a task pane.  here's a screen shot of the task pane with a XAML rectangle (which animates, but hey, it's a screenshot) and an embedded media element of a video.  you could think of documents that might be handbooks/trainings and include video with it so as the reader (or form-filler-outer) is looking at the document they might get live help via video:

i didn't get to the word content controls in my session, apologies.  we also didn't talk about sharepoint development, etc.  i think you could spend a whole time on that.  you tell me, what concerns you about sharepoint development?

i mentioned a few developer tips as well that i'll emit here:

    • remember 'Globals'
    • create a stub mail profile (control panel -- Mail) so when writing outlook applications you aren't constantly trying to connect with a real mail system.
    • click the 'office circle' and go to application options, add-ins, manage com add-ins to remove/clean up your developer litter

here are the slide decks: PPT 2007 and PDF

i hope that those who attended learned at least one thing new.  some of my demos weren't cooperating despite me staying up until 3am doing them three times.  such is life.  thanks again to those who came.  be sure to check out beth's post as she used VB XML literals to leverage Office Open XML to write a mail merge in XML code which generate word documents...it was pretty slick.