BTS Bits

Microsoft Customer Care Framework (CCF) - HAT Architecture

brajens — Sat, 05 Dec 2009 22:16:00 GMT

Introduction

Microsoft Customer Care Framework (CCF) is used to integrate and automate line of business (LOB) applications. CCF uses two modules “Application Integration Framework (AIF)” and “Hosted Application Toolkit (HAT)” for this purpose. AIF provides foundation and framework for application integration and automation, while HAT provides development toolkit for the same.

HAT development toolkit comes with software factory that developers can use to integrate LOB applications easily. In this article, I am going to cover high-level architecture of HAT.

Architecture of HAT

HAT makes use of 5 components and these components play different roles in development -

1. Line of Business Application

2. Automation

3. Automation Manager

4. Binding File (Init String)

5. Data Driven Adapter (DDA)

Kindly refer Figure1 in attached image to see logical architecture of HAT.[Sorry not able to insert image into body]

Lines of Business Applications are customer applications that developers want to integrate and automate for CCF implementation. CCF follows “No Rip and Replace” methodology and it does not require any changes in applications.

Automation is business logic or user activities which developers want to automate. The automation primarily consists of following tasks –

1. Navigation between pages

2. Read some data value from screen or page

3. Set some data in a control on screen or page

4. Click on button, check boxes, radio buttons, links, menu etc.

5. Call Web Services and other APIs etc.

Kindly refer figure 2 of attached image to see sample automation.

Developers use windows workflow foundation 3.0 or above within Visual Studio to develop business logic in HAT.

Automation Manager is runtime of AIF. It is extension of windows workflow runtime. Automation manager uses binding file and automation business logic to perform automation of LOB application at runtime.

Binding File or Init String is used to store application information and control definition of LOB application. Binding file typically holds following information –

1. Application URL or URI

2. Command line parameters (in case of windows application; if any)

3. Control definitions. As part of automation, we automate user activities on application controls. Binding file stores definitions of controls involved in automation.

Kindly refer figure 3 of attached image to see sample-binding file.

Developers can use HAT software factory in Visual Studio to build binding file. One binding file is created per customer application.

Data Drive Adapters (DDAs) come out of box with CCF framework. DDAs are responsible for executing automation on line of business applications. CCF comes with three out of box adapters –

· Windows DDA

· Web DDA

· Java DDA

As you can see, there is one DDA per application type. All windows smart client applications can be automated using single Windows DDA. Similarly, all web or java applications can be automated using their respective DDAs.

DDA is quite extensible and developers can easily extend or create new DDA for automation. Creating DDA for mainframe applications, DOS applications etc. are common practice in CCF world of development.

How Things Work?

Automation in CCF works as following -

1. Business logic is built in windows workflow (WF) using CCF specific activities. One CCF activity performs a single step such as execute control, get control value or set control value etc.

2. CCF specific activities are placed in sequential workflow library to build business logic.

3. CCF Automation manager runs WF based business logic. CCF automation manager is extension of windows workflow runtime.

4. Automation manager reads automation instruction from WF based business logic and makes use of application binding file and appropriate DDA to perform automation.

5. On one hand, Automation manager refers binding file to learn control definition where it has to perform automation, on the other hand automation manager instructs DDA to perform actual automation by passing relevant information – control definition, automation instruction etc.

Summary

You can see that HAT is quite extensible and decoupled component to perform automation on LOB applications. In coming article, I will write more about HAT components, their extensibility and usage.

Figure1-2-3.jpg

Generating Schema in BizTalk using existing XDR or XML file (error resolution)

brajens — Mon, 21 Jul 2008 11:47:00 GMT

Many times you don’t create message schema from scratch. Instead you try to generate schema using some existing DTD, XDR or even sample XML file. Recently, I was trying to generate schema using XDR and sample XML file and ran into small irritating problems. This encouraged me to share solution for them with you.

I right clicked on project to select “Add Generated Item” menu. Then I selected “Generate Schema” option on next screen and start using it. First message I got that I need to run “InstallWFX.vbs” script file (located in InstallDir:\Program Files\Microsoft BizTalk Server 2006\sdk\Utilities\Schema Generator” folder) to install necessary prerequisite to use this tool. This was informative message and I did the same. Just for information, you need to run “InstallDTD.vbs” script file to install necessary prerequisite to generate schema using DTD file.

After running “installWFX.vbs” script, I was expecting smooth sailing but I was bugged with an error message. Something like - “Could not find file or assembly Microsoft.BizTalk.TOM … “. It was little weird to see this error because this dll was already present in machine.

I looked for similar error on net and even in BizTalk documentation but could not find one. I was making hit and try. And finally; following steps made schema generation tool run –

· I searched for “Microsoft.BizTalk.TOM .dll” assembly on machine.

· Used “gacutil” to register this assembly in GAC

· Finally executed “InstallWFX.vbs” script again.

Sometime small issues create big hurdle in development and especially when you don’t find remedy for them anywhere. Hope you find this useful.

Receive or Pull Data from CRM using BizTalk

brajens — Mon, 03 Mar 2008 02:44:00 GMT

(Article works with CRM Dynamics 3.0 and BizTalk Server 2004 onwards)

BizTalk CRM adapter can be used to send or push data to CRM system from any other application system. For example, account data can be pushed to CRM server from commerce server. But when it comes to receiving or pulling data out of CRM, Adapter is not the way because it comes with send adapter only. Well, one can design to run a scheduled orchestration which pools CRM server to fetch required data using SOAP adapter and CRM web service. But pooling is not a smart way. Ideally, any scalable design should pull incremental data when any data change happens. You can call this event (data change/addition) driven incremental data receive.

Understanding Fundamentals

To design event driven incremental data receive, you have to use some of the in-house features of CRM. These features are – “Workflow” and “BizTalk Logic Extension” or “Callout”. Let’s talk little about these.

Microsoft CRM provides an event driven workflow framework on which developers can write custom logic. You can write a .net component and make it work under a workflow rule definition. Workflow rules can be bound to the following events that can be performed on an entity instance –

· Create

· Assign

· Change Status

For example, if you create a workflow which has a rule which is bound to run on create event for “contact” entity instance, then whenever an instance of “contact” entity is created, it will trigger workflow rule and rule will in reverse call .net component. You can learn more about CRM workflow @ https://msdn2.microsoft.com/en-us/library/aa685987.aspx .

“Business Logic Extensions” or “Callout” is another event driven framework in CRM. Callouts can be configured to run (a .net component) upon occurrence of some event. Callouts support following event for CRM entities –

· Create

· Update

· Delete

· Assign

· Status Change

· Merge

· Send Mail

Callouts can be two types of –

· Pre Callout – executes before occurrence of event

· Post Callout – executes after occurrence of event

For example, if you configure a post callout on create event of “contact” entity, then whenever an instance of “contact” entity is created, it will trigger configured post callout and callout will in reverse call .net component. You can learn more about CRM callout @ https://msdn2.microsoft.com/en-us/library/aa680495.aspx.

Both of these features are simple, configurable, require .net based coding and are very powerful. You are not required to be a CRM expert to use or implement them.

Designing Event Driven Incremental Data Import

There are few things which make “workflow” and “callout” a great instrument to design event based data pull –

· Both run when events like create, update, delete etc. occurs on CRM entities. Since these events occur when changes happen to entity instances; you can put logic in workflow or callout to read entity instance data just change and play with it. In other world, you can fetch incremental data change.

· Both are configurable

· As an event action, both can run .net components.

Let’s take a scenario and see how these things work together to give desired design.

Scenario: Contoso is an online retail company. It has an e-commerce site with commerce server at back end. And its customer care offices run CRM. Customers can call Contoso customer care center agents to update their profile, credit card and demographic information. Agents use CRM web client to perform job. Customers can also do the same job using self care portal which in reverse uses CRM web service to update information in CRM system. In both of these cases, customer contact information is updated in CRM system. Requirement is that “as soon as customer contact information is updated in CRM system; it should get synchronized to commerce server”.

In this overall requirement, underline statement requires customer contact data to be pulled from CRM system and get pushed into commerce system. You want to do incremental data update and want pull to happen only when any customer contact information is changed. Let’s see a simple possible solution for this -

Solution: here are step by step things I will like to do to implement this solution.

· I am assuming that customer accounts are implemented as “contact” entity in CRM system.

· First you create a BizTalk project. You add a schema having those fields or properties which we need to synchronize between CRM and Commerce.

· Then you add an orchestration. Orchestration will use a “Request-Response” port to read messages of schema type defined above. Once message is read, orchestration uses this message and commerce profile send adapter to send contact information into commerce system. Off course, there will some logic and data mapping between your schema and commerce profile schema. Well, I am sure smart implementation will have more decoupled and scalable orchestration design.

· When orchestration logic is complete, expose orchestration as web service and perform necessary port binding in BizTalk administrator.

· You are done with orchestration which can carry data between CRM and Commerce system. Now, we need to hook this orchestration with CRM in such a way that whenever contact entity instance is updated in CRM; it should trigger orchestration and pass required contact data from CRM to Commerce system.

· To perform required clip, create a workflow or post callout in CRM on “contact” entry and subscribe it to “update” event. As an action, workflow or callout will call a .net component and pass contact instance information to it.

· .Net component will call BizTalk web service exposed above and will use contact instance information to populate fields of schema in web service and finally call web service.

· And it works. Whenever, a contact entity instance is updated in CRM, configured workflow or callout will get triggered. Workflow or callout will fire .net component execution. Component will call web service passing contact instance information. Web service will pass data to orchestration and orchestration will push data into commerce system using adapters.

· That’s it. Solution triggers data synchronization only when any data change happens. Only incremental data is passed between systems.

· Well web service is one way. You can also used file, ftp or any other channel based integration.

Choosing between workflow and business logic extension (callout)

You saw that we can use both callout and workflow to implement pull solutions. Question is when to use workflow and when callout? You can use following guidelines –

· Callout supports more events than workflow.

· Workflows run asynchronous while callouts work synchronous.

· Callouts support all entities in CRM but workflow has reservations for few.

· Workflow can be run manually but callout cannot be.

· Callouts can be managed using automated deployment but workflow is not. One has to use workflow manager for workflow deployment.

Conclusion

Workflow and callout are two wonderful features in CRM which can be leveraged by BizTalk to write a smart pull operation. You just need to use their potential and fit in design. Hope you find this article useful.

Using Microsoft BizTalk Dynamics CRM Adapter – Part 5

brajens — Mon, 30 Jul 2007 05:38:00 GMT

Welcome to last article of this series. Today, we are going to talk about using some CRM specific field types such as “Lookup” and “Picklist”. We will also have little talk about using custom entities/attributes.

“Lookup” field is used to link two entities together. For example, when we create an account, we link account entity instance to a contact entity instance where contact is primary contact person for account. In this case, “lookup” type field is used to link account and contact entities. When you see account entity details and screen, you will find “Primary Contact” field as “Lookup” type.

“Picklist” is similar to options/combo control where user can select a value from existing set of values. For example, “Address Type” field of account entity is “Picklist” type with option values as “Bill To”, “Ship To”, “Primary” and “Other”. Picklist type fields can be displayed as combo box or radio buttons on entity form.

I strongly suggest checking my previous articles for complete context as I am keeping this article very short and to the point.

Using “Picklist” and “Lookup” fields in .net code (calling CRM web service)

I am going to create an account instance and would use both “Lookup” and “Picklist” type fields in code.

Procedure is the same; I added CRM web service as web reference and named it “CRMServer”. Following is code to update contact instance in CRM system.

CrmServer.CrmService service = new CrmServer.CrmService();

CRMServer.account myaccount = new CRMServer.account();

myaccount.name = "my account";

//Handling Lookup type field

CRMServer.Lookup primaryContactLookup = new CRMServer.Lookup();

primaryContactLookup.Value = new Guid("23e923d8-5cc6-4574-bd34-f1c43130a4bb");

primaryContactLookup.type = CRMServer.EntityName.contact.ToString();

myaccount.primarycontactid = primaryContactLookup;

//Handling picklist type field

CRMServer.Picklist addressTypePicklist = new CRMServer.Picklist();

addressTypePicklist.name = "address1_addresstypecode";

addressTypePicklist.Value = 2;

myaccount.address1_addresstypecode = addressTypePicklist;

System.Guid newAccountId = service.Create(myaccount);

I first created an instance of CRM web service client.

CrmServer.CrmService service = new CrmServer.CrmService();

Then I created instance of account entity and supplied name field which is required.

CRMServer.account myaccount = new CRMServer.account();

myaccount.name = "my account";

Next I am handling “Lookup” type field and linking account and contact entity instances. First, create a new instance of lookup type then assign value to “Value” and “Type” fields.
“Value” field is assigned value of “contactid” (primary key GUID) for contact to be linked. In your implementation, you can run query over contacts using “Fetch” or “Retrieve” method to get required contact and its internal id field “contactid” (primary key value). In “Type” field, we assign name of the entity we are linking to account entity. In our example, it is “contact” entity. You can use “EntityName” enumeration class to get contact entity name or can hard code to “contact” string value. However, first method is preferred. When lookup data is ready, we assign it to appropriate field in account entity.

//Handling Lookup type field

CRMServer.Lookup primaryContactLookup = new CRMServer.Lookup();

primaryContactLookup.Value = new Guid("23e923d8-5cc6-4574-bd34-f1c43130a4bb");

primaryContactLookup.type = CRMServer.EntityName.contact.ToString();

myaccount.primarycontactid = primaryContactLookup;

Now “Picklist” type. Coding is similar to lookup type field. Create an instance of “Picklist” type and then assign values for “name” and “value” fields. Each option provided by pick list has a numeric value assigned to it. For example in our case of “Address Type” field; following are numeric values assigned to text options - “Bill To” = 1, “Ship To” = 2, “Primary” = 3 and “Other” = 4.

In my sample, I selected option number 2 (text value “Ship To”). Name field contains schema name of “Address Type” field which in our case is "address1_addresstypecode”. Finally when pick list is populated; assign it to appropriate field in account entity.

//Handling picklist type field

CRMServer.Picklist addressTypePicklist = new CRMServer.Picklist();

addressTypePicklist.name = "address1_addresstypecode";

addressTypePicklist.Value = 2;

myaccount.address1_addresstypecode = addressTypePicklist;

Good, now time to call create method to create a new account.

System.Guid newAccountId = service.Create(myaccount);

Job Done.

Using “Picklist” and “Lookup” fields in BizTalk Orchestration (CRM Adapter)

Process is the same as we did in previous articles. Create BizTalk project and generate CRM entity schema using send port (CRM adapter based) and web service.

When you generate account schema for “create” operation, it generates a schema named “account_Entities.xsd” which is used to create request message for create account operation.

If you check “Primary Contact” (lookup type) and “Address Type” (pick list type) fields of account schema, it looks similar to what we did in .net code above.

“Primary Contact” field looks like following –

primaryaccountid

|__ IsNull

|__ name

|__ type

|__ dsc

We assign value similar to .net code –

Primaryaccountid ------------ assign value = "23e923d8-5cc6-4574-bd34-f1c43130a4bb" ---

|__ IsNull

|__ name

|__ type ---------------- assign value= “contact” ---

|__ dsc

“IsNull”, “name” and “dsc” fields are optional. Set “IsNull” field to true if lookup field is optional and you don’t want to populate this field. “Name” can hold schema name of lookup type field. And “dsc” can hold brief description about usage of this field. You can use some other message field or script functoid in map to assign these fields.

When we check “Address Type” field, it looks like following –

address1_addresstypecode

|__ IsNull

|__ name

Again, value assignment is similar to .net code -

address1_addresstypecode ------------ assign value = 2 --

|__ IsNull

|__ name ---------------- assign value= “address1_addresstypecode” ---

“name” and “IsNull” fields are optional. Set “IsNull” field to true if “Picklist” type field is optional and you don’t want to populate this field. “name” field is populated with schema name of the field.

Populate request message as directed above and you are all set to perform create account operation. Please refer previous articles to understand other required things as I have focused on populating “Lookup” and “Picklist” type fields only.

Using Custom Entities/Attributes

Using custom entities/attributes are no different than CRM system entities and attributes. Thanks to metadata driven approach used by CRM system which gives CRM extensibility to a new dimension. Once you create and publish a custom entity or custom attribute, it is ready for use in CRM web service and CRM adapter.

When using CRM adapter, you will see custom entities listed in schema generation process. Similarly, you will also find custom attributes listed in generated schema.

Similarly, when you use reference web service, you will find custom entities and attributes generate as part of proxy code.

In both of the scenarios mentioned above, it uses CRM metadata web service to fetch latest CRM schema and generate proxy code/schema based on that.

If you have already created one application using CRM web service and then updating CRM schema with custom entities/attributes then you need to update web service reference in application to get hold of updated entities/attributes.

On similar lines, if you already have a BizTalk application using CRM adapter and you make any change in CRM schema for custom entities and attributes, then you have to regenerate schema for consuming them.

Conclusion

You would have seen that “Lookup” and “Picklist” data types are little tricky but simple to use. Nice part is that custom entities/attributes do not make any difference to programming CRM. You just need to update web service reference or regenerate schema in case of BizTalk programming to get hold of changes.

Using Microsoft BizTalk Dynamics CRM Adapter – Part 4

brajens — Sat, 30 Jun 2007 13:12:00 GMT

We talked about create, delete, query and configuration details in previous articles. In current article, I am quickly going to summarize update operation with CRM system.

I suggest you refer my previous articles before reading current one. This will provide you complete context of things.

Next article in this series will be a final one in which I will talk about dealing with special attributes like (pick list, lookup etc.) and custom attributes/entities.

How to perform “Update” operation with CRM System

“Update” operation is lot similar to “Create” operation. Only difference is that you supply internal primary key (GUID) of entity instance along with other attributes to be modified. Internal primary key is used to identify entity instance in CRM system.

When updating an entity instance, keep in mind that you cannot provide blank or null values for a required attribute. Another point is that you just need to send values of those attributes only which you wish to update.

Perform “Update Contact Entity” instance using .net code (calling CRM web service)

I am going to write a sample code which will update some of the attributes (in this case “lastname”) of an existing contact entity instance.

I added CRM web service as web reference and named it “CRMServer”. Following is code to update contact instance in CRM system.

CrmServer.CrmService service = new CrmServer.CrmService();

CrmServer.contact contact = new CrmServer.contact();

CrmServer.Key contactKey = new CrmServer.Key();

contactKey.Value = new Guid("7e1120f8-2b15-4fc4-a347-59a702725c61");

contact.contactid = contactKey;

contact.lastname = "Marks";

service.Update(contact);

I first created an instance of CRM web service client.

CrmServer.CrmService service = new CrmServer.CrmService();

Then I created instance of contact entity and supplied internal primary key value (GUID) for “contactid” attribute. “contactid” attribute of contact entity holds primary key value of entity instance.

CrmServer.contact contact = new CrmServer.contact();

CrmServer.Key contactKey = new CrmServer.Key();

contactKey.Value = new Guid("7e1120f8-2b15-4fc4-a347-59a702725c61");

contact.contactid = contactKey;

Then I am supplying value for attributes which I wish to update. In this case, it is “lastname”.

contact.lastname = "Marks";

Finally, I called update method, passing contact object into it.

service.Update(contact);

Perform “Update Contact Entity” instance using BizTalk orchestration (using Dynamics CRM Adapter)

It is time to perform the same operation using BizTalk CRM adapter. I will quickly summarize things because reader’s who have read my previous articles have enough background about other details. I will primarily talk about entity, action to be selected and schemas to be used for messaging with CRM system.

· To update a contact, we need a solicit-response send port (say “CRMSendPort”) which can talk to CRM system using BizTalk CRM adapter.

· Create a BizTalk project.

· We have to generate schema for update operation. When you generate schema, select action as “Update” and entity as “contact”.

· It generates lots of schemas and one BizTalk orchestration file in project. Open orchestration file and delete all port types and multi-part message types generated by default. These are useful but I am asking to clean them so that you can create and understand things from scratch.

· We are interested in two schemas only – one request schema (to send details of contact to be updated) and one response schema.

· “contact_Entities.xsd” serves purpose of request schema. In our example, we need to set following fields/elements –

o “contactid” – it holds primary internal id (GUID) of contact to be updated

o “lastname” – supply updated last name value for contact

o “crm_action” – we can keep it blank because we have already supplied value of primary key and this instructs adapter to search for contact entity instance and perform update operation. But it is always good practice to provide action name. In this case, we supply “update” as “crm_action” value.

· Response is handled by “Respond.xsd” schema which can be found @ “C:\Program Files\BizTalkAdapter\Schemas” depending upon adapter installation location. You have to include this Response.xsd in project.

· When you are done with coding, compile project and deploy it. After deployment, bind solicit-response orchestration ports with physical solicit-response port (“CRMSendPort”) created in above steps. Enlist and start orchestration. Finally trigger orchestration to test update operation.

· That’s it.

Conclusion

You must have realized that “create” and “update” are very similar. Only difference is that for create, we don’t supply primary key value while it is must to provide in case of update operation. We are close to our journey. In next article, I will talk about special attributes and custom entities/attributes. Thanks for reading.

Using Microsoft BizTalk Dynamics CRM Adapter – Part 3

brajens — Fri, 29 Jun 2007 10:33:00 GMT

In previous articles, we talked about –

· Installing and configuring BizTalk CRM Adapter

· Basics of CRM System

· How to perform query operation using BizTalk adapter

· How to perform create operation using BizTalk adapter

I suggest you refer my previous articles before reading current one –

Part1: https://blogs.msdn.com/brajens/archive/2007/05/27/using-microsoft-biztalk-dynamics-crm-adapter-part-1.aspx

Part2: https://blogs.msdn.com/brajens/archive/2007/05/30/using-microsoft-biztalk-dynamics-crm-adapter-part-2.aspx

I am going to cover delete operation in current article. The very next article will talk about update operation.

How to perform Delete operation with CRM Adapter

As I mentioned earlier, you can consider a CRM system as sub-systems having information captured in entities. When performing delete operation, we actually delete instance of one the entity.

Since entities are related to each other, it is always good idea to check dependent entities and come up with logic to handle them when performing delete operation.

Perform “Delete Contact Entity” instance using .net code (calling CRM web service)

Let’s talk through an example. I am going to write.net code to delete one instance of entity “contact”.

I added CRM web service as web reference and named it “CRMServer”. Following is code to delete contact instance in CRM system.

CrmServer.CrmService service = new CrmServer.CrmService();

service.Delete(CrmServer.EntityName.contact.ToString(), new Guid("737ddf30-b7f7-4cff-a559-70ce250ee19b"));

Code is two liners. I first created an instance of CRM web service client.

CrmServer.CrmService service = new CrmServer.CrmService();

And then I called delete method. It takes two parameters – name of the entity whose instance it to be deleted and internal unique id (GUID) of the instance.

service.Delete(CrmServer.EntityName.contact.ToString(), new Guid("737ddf30-b7f7-4cff-a559-70ce250ee19b"));

Every entity instance has a unique primary key value (GUID) inside CRM system. You just need to pass this guid and entity name.

Perform “Delete Contact Entity” instance using BizTalk orchestration (using Dynamics CRM Adapter)

I am going to perform same delete operation using BizTalk CRM adapter. I am not going to take things in very detail because reader’s who have read my previous articles have enough background about it. I will primarily talk about entity, action to be selected and schemas to be used for messaging with CRM system.

· To delete a contact, we need a solicit-response send port (say “CRMSendPort”) which can talk to CRM system using BizTalk CRM adapter.

· Create a BizTalk project.

· We have to generate schema for delete operation. When you generate schema, select action as “Delete” and entity as “contact”.

· It generates lots of schemas and one BizTalk orchestration file. Open orchestration file and delete all port types and multi-part message types generated by default. These are useful but I am asking to clean them so that you can create and understand things from scratch.

· Out of generated schemas, we are interested in two schemas only – one request schema (to send details of contact to be deleted) and one response schema.

· “contact_Entities.xsd” serves purpose of request schema. There are two nodes/fields which are required to set – one is “contactid” and other is “crm_action”. Supply internal primary key value (GUID) to “contactid” element (same way we did in .net code above). Then supply “delete” as value for “crm_action” field.

Note: Whenever, you want to delete instance of any entity, it generates a schema with name “_Entities.xsd”. And this schema is used to form request message.

· That’s it.

Conclusion

We have quickly seen delete operation. I am writing these small segregated articles to check one operation at a time. Update operation is lot similar to create operation and we will go through it in very next article.

Using Microsoft BizTalk Dynamics CRM Adapter – Part 2

brajens — Wed, 30 May 2007 10:59:00 GMT

In previous part of the article, we had initial talks about integration between BizTalk and CRM using Dynamics CRM Adapter. We discussed –

· Installing and configuring BizTalk CRM Adapter

· Basics of CRM System

· How to perform query operation using BizTalk adapter

In this part of article of the article, I am going to take next baby step and talk about another operation “Create Data” in CRM System.

To take absolute advantage and context of this article, I suggest readers to go through previous part of the article @ https://blogs.msdn.com/brajens/archive/2007/05/27/using-microsoft-biztalk-dynamics-crm-adapter-part-1.aspx

How to perform Create Data with CRM Adapter

Using BizTalk CRM adapter, developers can create any entity (like account, contact, case, product etc.) inside CRM System. Before creating any entity, it is suggested to get following information about entity for CRM implementation at client site –

1. What attributes of the entity are supported? (you have to populate data for those attributes)

2. What attributes of the entity are required? Like “Title” is required field for entity “incident” or “case”. (you just cannot afford to miss populating data for these attributes; it will give error otherwise)

3. How many attributes of the entity are Pick List types (take options as value)? For example, “Priority” field of “incident” entity is Pick List type and it accepts Low, Normal and High as values. (there is a special way to populate Pick List type attributes)

4. Is this entity linked (has relationship) with other entities? If yes then what are the linking attributes? These fields are called “Lookup” fields. For example, “incident” is linked to “account” entity where “account” has parent entity role. An incident cannot be created unless linked to an account. “Incident” entity has a field as “Customer” where is shows parent account name information. Now, when you create an incident, it is must to provide parent account information because account-incident entities are linked as Parent-Child relationship.(there is a special way to populate Lookup type attributes)

5. Is this a custom entity? (there is a special way to populate custom entities)

6. What attributes of the entity are custom created? (there is a special way to populate custom attributes)

In this article, I will talk about out of box entities and their attributes. To reduce complexity, I will leave Pick List type attributes, Lookup type attributes, custom entities and custom attributes. But I promise to address this specifically in very next parts of the article.

1. Example Scenario

I am taking very simple scenario where I am creating new “contact” entity instance in CRM system. I have tried to keep it simple. The “contact” entity lies under “Service” sub module. Following are answers to my questions above –

1. What attributes of the entity are supported?

For this article, I am assuming that client CRM implementation supports following attributes of “contact” entity – “Last Name”, “First Name”, “Salutation”, “Job Title”, “Business Phone” and “Email”.

2. What attributes of the entity are required?

“Last Name” is only required attribute.

3. How many attributes of the entity are Pick List types?

“contact” entity has Pick List type attributes (like “Address Type”) but I am leaving it for next part of article.

4. Is this entity linked (has relationship) with other entities?

“contact” entity is linked to “account” entity and has a Lookup type attribute ( “Parent Customer”) but I am leaving it for next part of the article.

5. Is this a custom entity?

No, this entity is out of box provided by CRM System.

6. What attributes of the entity are custom created?

None so far. We will cover it in next part of article.

It’s coding time again.

2. Perform “Create Contact Entity” instance using .net code (calling CRM web service)

I added CRM web service as web reference and named it “CRMServer”. Following is code to create contact instance in CRM system.

CRMServer.CrmService service = new CRMWSTest.CRMServer.CrmService();

service.Credentials = System.Net.CredentialCache.DefaultCredentials;

CRMServer.contact contact = new CRMServer.contact();

contact.firstname = "Brajendra";

contact.lastname = "Singh";

contact.salutation = "Mr.";

contact.jobtitle = "Consultant";

contact.telephone1 = "111-111-1111";

contact.emailaddress1 = "test@microsoft.com";

Guid newContactId = service.Create(contact);

Code is fairly simple. I first created an instance of CRM web service client.

CRMServer.contact contact = new CRMServer.contact();

contact.firstname = "Brajendra";

contact.lastname = "Singh";

contact.salutation = "Mr.";

contact.jobtitle = "Consultant";

contact.telephone1 = "111-111-1111";

contact.emailaddress1 = "test@microsoft.com";

Then I created an instance of “contact” class and set values for attributes. Few things need attention here –

· You will get error if you don’t populate “lastname” property because it is a required field for “contact” entity.

· If you see scenario above, we talked about “Business Phone” and “Email” attributes. But here I am populating “telephone1” and “emailaddress1” properties. This mean, In CRM system, for contact entity, “Business Phone” is display name for schema name “telephone1” and “Email” is display name for “emailaddress1”. You can check all these details on customization section of CRM application and please refer part-1 of article for more information on it.

Guid newContactId = service.Create(contact);

Finally, you call create method for service. “Create” method is service takes “BusinessEntity” type as parameter. All entities in CRM system inherits from “BusinessEntity” class. This makes “Create” a generic method to create all entities inside CRM system.

When you create an entity; you get a GUID as return value and it contains internal id (primary key) of that entity instance inside CRM system. Guid returned in this example is internal id of created new contact in CRM system and it is hold by “contactid” attribute of contact entity.

So far so good, let’s implement the same code in BizTalk using BizTalk adapter.

1. Perform “Create Contact Entity” instance using BizTalk orchestration (using Dynamics CRM Adapter)

Following are the steps to perform same create contact operation in orchestration using BizTalk Dynamics CRM adapter.

· To create a new contact, we send contact information in XML message and get response XML back containing internal id (primary key) of created contact. We need solicit-response send port for this purpose. Create a new static solicit-response send port in BizTalk Administration Console. Give a name to it (say “CRMSendPort”) and select type as “Microsoft Dynamics CRM” to make it use CRM adapter. Go to “Configure” and put “Web Service URL” as https:///mscrmservices/2006.

In send handler, select send handler created as per CRM specific host. Configure “Send Pipeline” as “Xml Transmit” and “Receive Pipeline” as “Xml Receive”. Save and close things.

· Create a BizTalk project and assign a strong name key to it.

· We have to generate schema for create operation. Right click Project Name >> Select Add Menu >> Select Add Generated Items Menu>> Select Add Adapter Metadata Option>> Press Add Button >> Select Microsoft Dynamics CRM Option>> Select Port (same port created in above steps say “CRMSendPort”) >> Press Next Button. “Microsoft Dynamics CRM User Credentials” screen opens up. Enter user name and password for CRM system. Remember this user name and password should have adequate access to fetch entity and their schema information from CRM system. Press Ok button after entering credentials.

· “Microsoft Dynamics CRM Actions and Entities” screen opens up. As we already discussed, CRM sub-systems are made of entities. At this point we select entity which we want to deal with and action which we want to perform on selected entity. Since we want to create an instance of contact, select “Create” as action and “contact” as entity. If required, in some implementation, you can also select multiple actions and multiple entities. When selection is done, press next button. It would take few seconds to generate all schemas related to fetch operation in BizTalk project.

· In generated artifacts, it has lots of schemas and one BizTalk orchestration file. Open orchestration file and delete all port types and multi-part message types generated by default. Well, these are useful but I am asking to clean them so that we can create and understand things from scratch.

· It generates quite a number of schemas in project. These schemas contain type definition and are included in each other. We are interested in two schemas only – one request schema (to send contact details) and one response schema (containing internal id or primary key of created contact).

· “contact_Entities.xsd” serves purpose of request schema. You expand to see details of this schema; it contains all supported properties of contact entity and “crm_action” attribute.

Note: Whenever, you want to create instance of any entity, it generates a schema with name “_Entities.xsd”. And this schema is used to form request message.

· Response is tricky again. Developers think that “Create_CreateResponse.xsd” is response schema but it is NOT. Every response using CRM adapter follows a fix and common schema and this schema is not generated. You can find this schema @ “C:\Program Files\BizTalkAdapter\Schemas\Response.xsd” depending upon adapter installation location. You have to include this Response.xsd in project.

· We are now all set to implement logic. Create two messages of type request and response schemas. Hook these messages to a static solicit-response send logical port using send and receive shape. Use map (with transform shape) or message assignment shapes to create request xml and send it via solicit-response port. When response comes consume it as per requirement. I am leaving this logic development part to readers. If you face any issue, please refer sample application attached with this article or feel free to message me.

· When creating xml request (using map or message assignment), take care of following things. Set “crm_action” attribute value to “create”. We are doing this because we are performing create operation on CRM system. Set values for all the contact attributes discussed above. Please do not forget to set value for “lastname” attribute because it is required attribute. In attached sample, I have used another XML schema in map to prepare request XML. This same XML schema based message is copied at a file based receive location to kick start sample orchestration. I have implemented in crude way to keep things simple but you can have implementation as per your requirement.

Note: Few words about setting “crm_action” attribute. When performing create operation, it is always safe and good to provide “create” as value in “crm_action” attribute. However, if “crm_action” value is not provided then it uses following logic to take decision –

o If the primary key node of the entity (in this case contactid) is not present in the XML or if the node has an empty value, the adapter assumes this is a “create” action.

o If the primary key node of the entity has a correct GUID value, the adapter assumes the action to be “update”.

· You will find that response message comes in following format –

84bc5a78-22c6-4cc9-88e6-3043c558bf37

“Message” element contains response (xml format) and it follows schema type “Create_CreateResponse.xsd”. You will find that response XML contains internal id (primary key) of created contact entity instance. You need to employ some parsing technique to fetch id out of response xml.

Rest of the return message contains error handling mechanism which can be used as required.

· That’s it.

Conclusion

We have seen query and create operation in part 1 and 2 of the article. I am going to take complex scenario of create operation in next article. If required, please download sample project attached with article for further reference. If you face any issue please feel free to ping me on this article. Hope article was useful to you and your comments are always welcome.

CreateContactOrch.zip

Using Microsoft BizTalk Dynamics CRM Adapter – Part 1

brajens — Sun, 27 May 2007 08:14:00 GMT

Recently, I have been working on an integration project where few exiting systems were getting integrated with Microsoft CRM System 3.0. We architected to use BizTalk CRM adapter to synchronize and integrate data with CRM system. We could not locate a good documentation about adapter usage. We had to do lots of research, hit-&-try POCs to understand CRM adapter usage. And this encouraged me to come up with set of articles which can facilities developers to understand and use adapter easy and fast.
I am thinking to cover some basic operations with BizTalk CRM adapter such Query Data, Create Data, Update Data, Delete Data, Execute Operations, Retrieve Data etc. I will also cover dealing with complex data types (Pick List, Lookup) and custom entities/attributes.

I am expecting reader to have basic understanding of schemas, maps, orchestration, ports and adapters.

How to Install BizTalk CRM Adapter

Adapter installation is simple. You can download installation bits and usage guide from https://www.microsoft.com/downloads/details.aspx?FamilyID=4628fca6-388d-45bc-a154-453b920dbcb8&displaylang=en.

Following are key points of installation and usage guide –

1. Installation is simple and setup based.

2. CRM system uses AD based security schema. BizTalk uses send or solicit-response ports with CRM adapter to talk to CRM system. BizTalk ports run under host. If your BizTalk host service account does not have adequate access on CRM system then you are required to create another host with account which has sufficient access permission on CRM system. And then you construct a new CRM send handler which runs under new host and then configure CRM related ports to run new CRM send handler.

3. Installation guide also talks about creating port and generating schema which I will also cover in coming sections.

4. I recommend readers to install CRM SDK which holds good quantity of code samples and information. You can find SDK @ https://www.microsoft.com/downloads/details.aspx?familyid=9C178B68-3A06-4898-BC83-BD14B74308C5&displaylang=en.

5. It is useful to take look at overall installation and usage document. Especially known issues section.

Basics of CRM System

Before we chat about using CRM adapter, we will cover some nuts and bolts which are essential for any BizTalk developer to work with CRM. CRM application can be access using following URL (though it depends on configuration of CRM site) - https:///loader.aspx.

You will find that CRM system is divided into multiple sub-systems such Sales, Marketing, Service etc. With extension of CRM GP, accounting sub-systems also come in picture. Each of these sub-systems maintains a range of information like “Service” sub-system maintains Cases (customer escalations), Accounts, Contacts, Products etc.

In technical vocabulary, information is hold by various entities like we have one entity each for case, account, contact etc. These entities generally hold association/relationship among themselves. For example one account can have multiple contacts, one contact can have more than one case, there is many-to-many relationship between accounts and products etc.

Each of these entities follows a schema. Schema defines attributes hold by these entities and their type information. For example contact has Last Name (string), First Name (string), Gender (Pick List) etc as attributes. If you require then you can also create new custom entities or new custom attributes. When working with CRM system, we generally deal with these entities and their attributes. We create, update or delete instances of these entities.

Before we start integration with CRM system we need to understand entities, their schema, relationship with other entities etc. You can go to “Settings >> Customization >> Customize Entities” to see list of entities available in CRM system. List shows name, schema name, type and description. Here you will find option to create new custom entity or modify existing entity.

If you open (double-click) any existing entity, it will show you details of it. You will see details of attributes, forms/views to populate these entities in CRM system, relationship with other entities etc. When you check “Attributes” of entity, you will see attribute schema name, display name, type and description. Attribute schema name and type is very important information because BizTalk CRM adapter generates schema based on schema name and type information inside CRM system. You will also find provision to create new custom attributes.

CRM sub systems, forms, entities, schemas and customization are self explanatory. I suggest readers to spend some time with it; play around and get comfort.

It is time to get into coding now.

How to perform Query Data with CRM Adapter

Dynamics CRM provides a web service which can be used by developers to do operations against CRM system. CRM Adapter internally uses this web service for operations. Generally, you will find web service URL as –

https:///MSCRMServices/2006/CrmService.asmx.

Without documentation, it was hard for me to perform POCs with BizTalk CRM adapter. To make my job simpler, I played around with Dynamics CRM web service to manipulate entities. And this gave me adequate idea when dealing with generated CRM schemas in BizTalk. I am planning to follow same trick in these articles also - .Net code first and then BizTalk implementation.

We are going to see how query can be performed against CRM system. I am going to query case details using case guid. Case is complaints or service requests registered by customers and it comes under “Service” sub-system.

1. Perform Query using .net code (calling CRM web service)

I added CRM web service as web reference and named it “CRMServer”. Following is code to query case using case guid.

CRMServer.CrmService service = new CRMWSTest.CRMServer.CrmService();

service.Credentials = System.Net.CredentialCache.DefaultCredentials;

string fetchXml = @"

string result = service.Fetch(fetchXml);

Code is easy to understand. I first created an instance of CRM web service client and then create query (fetch) XML. Fetch xml is straightforward to understand.

Means entity which I wish to query is “incident”. Well, case is the display name and schema name for case is “incident”. You can find this in customization section as mentioned in previous section.

I am querying “Case Number” and “Title” attributes of case. Schema name of these two attributes are “ticketnumber” and “title”. You can add more attributes as required.

This is filter condition to query. Type is “and” as logical operator. It can also accept “or”. “attribute” is entity attribute which we are using for query. Again this is schema name not display name. “operator” is assignment operator and it can accept values as “lt” (less than), “gt” (greater than), “le” (less than or equal), “ge” (greater than or equal), “eq” (equal), “ne” (not equal), etc. Finally “value” holds value of attribute to be queried. If required, you can use more attributes with “and/or” options. I suggest readers to refer CRM SDK for more details about fetch xml.

Finally we call “Fetch” method passing “fetchXml” as parameter.

Query result comes in following format.

CAS-01006-ZBEJ0W

This is test case1

Result is self illustrative. You can see ticket number and title returned for query.

2. Perform Query BizTalk code (using Dynamics CRM Adapter)

Above was query implementation in .net code. Now we are going to implement same logic in BizTalk orchestration. Following are the steps to perform same query operation in orchestration using BizTalk Dynamics CRM adapter.

· In query we send Fetch XML and return result. We need solicit-response send port for this purpose. Create a new static solicit-response send port in BizTalk Administration Console. Give a name to it (say “CRMSendPort”) and select type as “Microsoft Dynamics CRM”. Go to “Configure” and put “Web Service URL” as https:///mscrmservices/2006.

In send handler, select send handler created as per CRM specific host in above section. Configure “Send Pipeline” as “Xml Transmit” and “Receive Pipeline” as “Xml Receive”. Save and close things.

Note: One of the common mistakes committed by developers is to put complete web service URL (https:///MSCRMServices/2006/CrmService.asmx) in configuration. This generates error during schema generation. Reason is that CRM adapter uses “Metadata.asmx” to generate schema and it just need URL of CRM web service virtual directory.

· Create a BizTalk project and assign a strong name key to it.

· We have to generate schema for query operation. Right click Project Name >> Select Add Menu >> Select Add Generated Items Menu>> Select Add Adapter Metadata Option>> Press Add Button >> Select Microsoft Dynamics CRM Option>> Select Port (same port created in above steps say “CRMSendPort”) >> Press Next Button. “Microsoft Dynamics CRM User Credentials” screen opens up. Enter user name and password for CRM system. Remember this user name and password should have adequate access to fetch entity and their schema information from CRM system. Press Ok button after entering credentials.

· “Microsoft Dynamics CRM Actions and Entities” screen opens up. As we already discussed, CRM sub-systems are made of entities. At this point we select entity (account, contact, case etc.) which we want to deal with and action (add, update, delete, execute etc.) which we want to perform on selected entity. Since we want to perform query on cases (incidents), select “ExecuteFetch” as action and “Incident” as entity. If required, in some implementation, you can also select multiple actions and multiple entities. When selection is done, press next button. It would take few seconds to generate all schemas related to fetch operation in BizTalk project.

· In generated artifacts, it generates lots of schema and one BizTalk orchestration file. Open orchestration file and delete all port types and multi-part message types generated by default. Well, these are useful but I am asking to clean them so that we can create and understand things from scratch.

· It generates some 10 schemas in project. These schemas contain type definition and are included in each other. We are interested in two schemas only – one request schema which can send our query/fetch XML and one response schema which can pull result back.

· “ExecuteFetch_ExecuteFetchRequest.xsd” serves purpose of request schema. You expand to see details of this schema. It has two important elements – “crm_action” and “FetchXml”. We will check these in details in few seconds.

· Now response is tricky part. Developers think that “ExecuteFetch_ExecuteFetchResponse.xsd” is response schema but it is NOT. Every response using CRM adapter follows a fix and common schema and this schema is not generated. You can find this schema @ “C:\Program Files\BizTalkAdapter\Schemas\Response.xsd” depending upon adapter installation location. You have to include this Response.xsd in project.

· We are now all set to implement logic. Create two messages of type request and response schemas. Hook these messages to a static solicit-response send logical port using send and receive shape. Use map (with transform shape) or message assignment shapes to create request xml and send it via solicit-response port. When response comes consume as per requirement. I am leaving this logic development part to readers. If you face any issue, please refer sample application attached with this article or feel free to message me.

· When creating xml request (using map or message assignment), take care of following things. Set “crm_action” attribute value to “execute”. We are doing this because we are executing fetch operation on CRM system. Other possible values are “create”, “update” and “delete”. We will see use of this in coming articles. Set “FetchXml” element value to - ""

Remember this is same format which we used in previous .net code sample. In attached sample, I used script functoids in map to prepare request XML. I have implemented in crude way to keep things simple but you can do better and smart job.

· You will find that response message comes in following format –

“Message” element contains response (xml format) and it follows schema type ExecuteFetch_ExecuteFetchResponse.xsd. You need to employ some parsing technique to fetch information out of response xml.

Rest of the return message contains error handling mechanism which can be used as required.

· That’s it. Make tweaks in request message and orchestration logic to explore query/fetch option thoroughly.

Conclusion

This was a high level walk through and a sample to query CRM system for entities. If required, please download sample project attached with article for further reference. If you face any issue please feel free to ping me on this article. Hope article was useful to you and your comments are always welcome.
Please wait for some time before we meet again with next part of it.

Next Part URL - https://blogs.msdn.com/brajens/archive/2007/05/30/using-microsoft-biztalk-dynamics-crm-adapter-part-2.aspx

QueryIncidentOrch.zip

Accessing Description / Metadata (WSDL) of WCF Web Service

brajens — Thu, 26 Apr 2007 07:02:00 GMT

WSDL or service metadata is the core for accessing or using any web service. In ASMX web service, browsing WSDL is straight forward. You develop a web service, host inside IIS and then simply browse ASMX file to view WSDL. But things are not the same with WCF service. If you try to access WCF service endpoint it says – “Metadata publishing for this service is currently disabled”. This is a common issue encountered by most of the beginners in WCF development. This results into confusion that there is something wrong with coding of WCF service while it is not true in most of the cases. So what is the reason for this message?

As a part of WCF security schema, by default no web service is allowed to share their description or Metadata unless they are configured to do so. You develop your service, test it and finally publish to production. But publishing web service to production will not enable service to be accessible unless service is configured to exchange its metadata. This is default security configuration of WCF service which blocks WSDL to be shared with users/developers.

How to make WSDL visible? This is very simple and can be achieved in following few steps.

1. WCF web service talks using end points. End point contains access address, binding and exposed contract. WCF provides out of box contract (IMetadataExchange) and binding (mexHttpBinding) to expose metadata of developed WCF web service. We just need to add this end point into service definition. Example:

<service name="MyNamespace.MyServiceType">

  <endpoint contract="IMetadataExchange" binding="mexHttpBinding" address="mex"/>

service>

2. WCF is a great example of decoupled extensibility. You can define services behavior separately then apply them to your services as required. Allowing metadata/WSDL exchange is one the service behavior (serviceMetadata) in WCF. We need to add this service behavior to services which further instructs or say allows services to expose their WSDL –

First Add service behavior –

<behaviors>

    <serviceBehaviors>

        <behavior name="MyServiceTypeBehaviors" >

            <serviceMetadata httpGetEnabled="true" />

        </behavior>

    </serviceBehaviors>

</behaviors>

If your service is exposed at https then you configure the same using “httpsGetEnabled”.

Finally enable service behavior in configured service

<service name="MyNamespace.MyServiceType" behaviorConfiguration="MyServiceTypeBehaviors" >

<endpoint contract="IMetadataExchange" binding="mexHttpBinding" address="mex"/>

service>

That’s it. These simple steps enable your services to start exchanging their description. This also provides a handy way to take WSDL visibility offline as required. Thanks for reading!

Exception Handling in WCF Web Service

brajens — Mon, 23 Apr 2007 06:04:00 GMT

Exception handling in ASMX web services was a painful job. Information was getting lost over wire / serialization; it was tricky to get fault code back and having a strongly type mapping between service raised exception and client consumed exception was a cumbersome task.

But things are not the same with windows communication foundation (WCF) service. In WCF, you can define a custom fault exception, get it populated and raised at service side as per error/exception and then nicely consume the same at client side. I am going to cover exception handling aspects of WCF service in this blog using an example.

In WCF development, exception handling method is very simple and it uses concept of contract definition. Just like data and service contract, you can also define fault contract and add behavior to it in service behavior. Let’s start with following example,

First define a data contract which you want to use to capture service side fault/exception,

[DataContract]

public enum FaultCode

{

[EnumMember]

ERROR,

[EnumMember]

INCORRECT_PARAMETER

}

[DataContract]

public class SampleFaultException

{

[DataMember]

public FaultCode errorcode;

[DataMember]

public string message;

[DataMember]

public string details;

}

I have defined a data contract SampleFaultException which contains three data members “errorcode”, “message” and “details”. “errorcode” is of type FaultCode which is an enum containing two members “ERROR” and “INCORRECT_PARAMEMERTS”.

Now define a service contract. I am using a simple service contract with one method only,

[ServiceContract]

public interface ISampleService

{

[OperationContract]

[FaultContract(typeof(SampleFaultException))]

int DevideNumber(int x,int y);

}

You can see that FaultContract of type SampleFaultException is annotated in operation contract details. This means “DevideNumber” will handle appropriate faults/exceptions using SampleFaultException. If you expect more types of faults to occur then you can define more fault contracts and place them in operation contract.

Contract definitions are over. Let’s implement a service over them,

public class SampleService : ISampleService

{

public int DevideNumber(int x, int y)

{

try

{

if (y > x)

{

SampleFaultException error = new SampleFaultException();

error.errorcode = FaultCode.INCORRECT_PARAMETER;

error.message = "value of y can not be greater than x";

error.details = "trying to devide with bigger value";

throw new FaultException<SampleFaultException>(error);

}

return x / y;

}

catch (DivideByZeroException dex)

{

SampleFaultException error = new SampleFaultException();

error.errorcode = FaultCode.ERROR;

error.message = "zero value passed for parameter y";

error.details = dex.StackTrace;

throw new FaultException<SampleFaultException>(error);

}

catch (Exception ex)

{

throw ex;

}

Implemention is quite simple. I am returing x/y in main flow. As part of exception handling logic, in one scenario, I am raising exception in try block as per parameter values. In other, I am casting DivideByZeroException exception into fault contract type SampleFaultException.

Service is ready. Let’s host them in IIS. You can also do selft hosting, windows service based hosting or WPAS (also called WAS) based hosting. I created a virtual directory; and placed a “.svc” file and web.config files.

Add service name in host “.svc” file –

<%@ServiceHost Debug="true" Service="WCFExceptionHandling.SampleService" %>

Add service defintion in web.config file –

<system.serviceModel>

behavior>

serviceBehaviors>

behaviors>

<endpoint address="" binding="basicHttpBinding"

contract="WCFExceptionHandling.ISampleService" />

service>

services>

system.serviceModel>

“WCFExceptionHandling” is the namespace of the service I created.

Finally I created a “bin” folder under virtual directory and added dlls containing contracts and services. I accessed URL (some thing like “https://localhost//.svc”) of hosted service to check if it is showing contract defintions through WSDL.

Things which need attention here are service behaviours. “includeExceptionDetailInFaults” is instructing services to include exception details in faults. “httpGetEnabled” allows services to expose their contract definition through WSDL. You have to enable both of these service behaviours explicitely which are by default flagged off due to security reason. By default WCF service does not reveal its information unless instructed to do so as done above.

It is time to consume this service. I created a windows projects and added service reference for service URL created above. When creating service reference, I added alias name as “WCFService”. Finally I wrote following client code –

try

{

WCFService.SampleServiceClient client = new WCFService.SampleServiceClient();

int returnValue = client.DevideNumber(4, 2);

}

catch (FaultException faultEx)

{

MessageBox.Show(faultEx.Detail.errorcode);

MessageBox.Show(faultEx.Detail.message);

MessageBox.Show(faultEx.Detail.details);

}

catch (Exception ex)

{

MessageBox.Show(ex.Message);

}

You can see that I am creating an instance of service client and then making call to “DevideNumber” method. Interesting part of code is how “SampleFaultException” is handled. “faultEx.Detail” provides every details you captured at service side. I tested this service with 4 and 2 as parameters and it returned 2 (nothing great). When I passed 4,0 as parameters, it raised fault exception with faultEx.Detail.message = "zero value passed for parameter y". And when I passed 4,6, it again raised fault exception with message = “value of y can not be greater than x". Interesting because I am able to capture every thing exactly the same as service raised in exception.

As illustrated through example, You can capture and consume every bit of your exception with simple and extensible approach provided by WCF services. Hope this articles was helpful to understand expection handling methodology in WCF services.