Building a Simple IBF solution - For Beginners, Part 1
I have been working for quite some time on the creation of a simple application
for IBF beginners. I would like to pen down my experiences for the
benefit of those who have just started or intend to start building IBF based
solutions, but are still in search for a simple application that could be used
as a reference.
The application being built here is a simple one inspired from the traditional
"Hello World" examples, with a minor difference - here we shall say hello to
a friend, rather than to the entire world. The focus here will be on exploring
the nascent IBF concepts. The application will deliberately avoid using database
access to keep things simple and also to make it easily testable in any environment
with very few dependencies.
Given below is an overview of how we shall proceed with building this
application.
1) Define the functionality that we would like to expose to users of Office
applications.
2) Identify the entities, views & operations that constitute the IBF solution.
Create XML representations for the same.
3) Create an IBF compliant Web Service
4) Use the Metadata explorer to create the Metadata to be published to the IBF
Service.
5) Develop the SmartTag Recognizer component to enable Office applications to
recognize the name of our friends.
6) Develop the UI to render the results returned by the IBF compliant Web
service.
So lets begin!!!
STEP 1: Define the functionality to be exposed to Office users.
Typical use case scenario for the application
a) User opens a Word document containing the name of friend(s).
b) When the user hovers the mouse over the name, a smart tag icon appears.
c) User clicks the "Show Details" menu item.
d) IBF task pane appears containing a text box that has the greeting message for
the friend selected by the user. eg: If the user clicks the "Show Details" for a
friend named "John", the IBF task pane comes up with a textbox displaying the
message "Hello John".
e) The IBF task pane will have a caption titled "Greeting Message for <friend
name>". "Caption Undefined" is a frequently encountered message due to minor
mistakes in the Metadata definition. I will try to put this issue to rest in
this series of articles.
We shall refer to this application as the "Greeting Service" from here onwards.
STEP 2: Identify the entities, view & operations that constitue the IBF
solution. Create XML representations for the same.
NOTE: Please refer to the IBF documentation for formal definition of Entity, Views & Operations.
a) In our sample solution, we have "Friend" as an Entity, because a "Friend"
object will be used as the starting point for invoking IBF Services. The name of
the friend is used to build a greeting message. Optionally, the name of the
friend can be used to decide the type of message to be returned. Currently our
IBF compliant "Greeting Service" greets each friend with the same message "Hello <friend name>".
XML representation of an instance of friend entity is given below
<Friend name="John"/>
FriendSchema: XML Schema for Friend entity
<xs:schema elementFormDefault="qualified" xmlns:xs="
http://www.w3.org/2001/XMLSchema">
<xs:element name="Friend">
<xs:complexType>
<xs:attribute name="Name" type="xs:string" use="required">
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:schema>
b) In the "Greeting Service" application, each Friend entity would have a
greeting message associated with it. Hence, we shall define a view named
"GreetingMessage".
XML representation of an instance of GreetingMessage view is given below
<GreetingMessage>
<Salutation>Hello</Salutation>
<Name>William</Name>
</GreetingMessage>
GreetingMessageSchema: XML Schema for GreetingMessage view
<xs:schema elementFormDefault="qualified" xmlns:xs="
http://www.w3.org/2001/XMLSchema">
<xs:element name="Salutation" type="xs:string">
</xs:element>
<xs:element name="GreetingMessage">
<xs:complexType>
<xs:sequence>
<xs:element ref="Salutation">
</xs:element>
<xs:element ref="Name">
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Name" type="xs:string">
</xs:element>
</xs:schema>
c) The "Greeting Service" application will provide a "get" operation to allow
the user to retrieve the greeting message associated with a friend name. Given
below is a XML Representation of this operation.
<Operation Name="GetGreetingMessage" EntityName="Friend" >
<InputSchemas>
<SchemaInstance SchemaName="FriendSchema" Index="1" />
</InputSchemas>
<OutputSchemas>
<SchemaInstance SchemaName="GreetingMessageSchema" Index="1" />
</OutputSchemas>
</Operation>
With these XML definitions of entities, view & operations, we have now laid the
foundation for creating the Metadata and the IBF-compliant Web Services.
STEP 3: Create IBF-compliant Web Service.
a) Open VS.NET and select Visual C# ASP.NET Web Service project. Enter directory where project should get created. Name the Project as IBFSimpleSolution.
b) Delete Service1.asmx and add a new Web Service file named SayHello.asmx to the project IBFSimpleSolution.
c) Switch to the code view of SayHello.asmx. We add two class definitions to
this file to correspond to the entity Friend & the view GreetingMessage
identified in STEP 2(a) & 2(b) respectively.
[XmlRoot("Friend", Namespace="urn-GreetingService-Data")]
public class Friend
{
private string name;
[XmlAttribute("Name")]
public string Name
{
get { return this.name; }
set { this.name = value; }
}
}
[XmlRoot("GreetingMessage", Namespace="urn-GreetingService-Data")]
public class GreetingMessage
{
private string salutation;
private string name;
[XmlElement]
public string Salutation
{
get { return this.salutation; }
set { this.salutation = value; }
}
[XmlElement]
public string Name
{
get { return this.name; }
set { this.name = value; }
}
}
d) Now define the Web Service class that will expose the the operation
GetGreetingMessage and a simple interface to the test the operation
GetGreetingMessage.
/// <summary>
/// Web Service class that provides greeting messages
/// </summary>
[WebService(Name="Greeting Service",
Description="A Service to send out greeting messages",
Namespace="http://InformationBridge/SayHello")]
public class SayHello : System.Web.Services.WebService
{
private GreetingMessage greetingMessage;
[WebMethod(Description="A method that provides a message to be used to greet a friend")]
public GreetingMessage GetGreetingMessage(Friend aFriend)
{
greetingMessage = new GreetingMessage();
greetingMessage.Salutation = "Hello ";
greetingMessage.Name = aFriend.Name;
return greetingMessage;
}
[WebMethod(Description="A method to test the function GetGreetingMessage
using HTTP")]
public GreetingMessage TestGetGreetingMessage(string aFriendName)
{
Friend friend = new Friend();
friend.Name = aFriendName;
return GetGreetingMessage(friend);
}
}
e) Test the Web Service by invoking it through the browser.
http://localhost/IBFSimpleSolution/SayHello.asmx
Given below is a screenshot of the Web service Test Screen.
The screen given below appears when the link TestGetGreetingMessage is clicked. We supply John as the name of the friend & then click Invoke button.
After the Invoke button is pressed the method returns output in the XML format shown below.
With the Web Service successfully tested, we can concentrate on describing
this application using IBF terminology of Ports, Actions, Transformations,
etc... so that the IBF engine on the client end can interpret & act on the
data made available by the "Greeting Service". We shall focus on metadata creation &
presentation of IBF data in Office documents in the up-coming blogs.
Thats all for today.