Introduction

To consume web services using the generic entities, software developers can connect to web services with any platform and/or environment which supports the SOAP protocol. This document provides a step-by-step guide using Microsoft Visual Studio 2008 as an example.

Description

1. Open Microsoft Visual Studio 2008.

2. Create a new project with the following information:

• Project type: Expand Visual Basic, and then click Windows.
• Templates: Windows Forms Application.
• Name: TestApplication.
  
  

3. Add a service reference to Metadata service:

• Right-click the TestApplication project, and then click on Add Service Reference…
• In the Address box, enter a valid service URL. For example: http://localhost/Synergy/Services/Exact.Metadata.svc and click Go.
• At Namespace, type Metadata.
  
  

4. Open app.config and increase the sizes of maxBufferSize and maxReceivedMessageSize. You can change the size at anytime in order to receive the metadata information successfully from the service.

5. Open the Form1 class in the Designer window.

• In this example, a Button and a TreeView are added to interact with the metadata service.
  
  

6. Open the Form1 class in the Code Editor window and add the following code:

• Declare the variables that will hold the metadata object.
  
  

• In this example, set client credential as Impersonation.
  
  
  
• An alternative way of setting the credential is by passing a valid username and password to the network credential.
  
      entityClient.ChannelFactory.Credentials.Windows.ClientCredential = New System.Net.NetworkCredential("username", "password")

• Add the code in the <Metadata> button and click Event to retrieve the metadata information (the Item metadata is used as an example here; you can retrieve metadata for Account, Document, Resource, Request, Project as well):
  
      metadataEntity = metadataClient.Retrieve(“Item”)  

• Debug the application. You will see metadataEntity now loaded with the metadata information for the Item. You can then populate the information into the TreeView control.
  
  
   
• Run the application and click the <Metadata> button. All the Item properties are now presented in the TreeView control.
  
  

7. Now, open the Form1 class in the Designer window.

• Extend Form1 by adding more buttons, labels, text boxes, and check boxes:
  
  

8. Open the Form1 class in the Code Editor window and add the following code:

• Declare the variables that will hold the Entity objects.
  
  

• Add an initialization code to Entity objects.
  •    This example uses Item. Other entities can be called by supplying the correct entity name, such as Account, Document, Resource, Request, and Resource.
    
    
     
• Add the Helper function to assign the entity's values to the correct text boxes.
  • The generated proxy for the properties of a generic entity is not name-indexed. Therefore, create a Helper function to assist in assigning the correct property value to the correct holding control.
    
    

• Add code in <Create> button. Click the button to create an item by:
  • Assigning all the text box values into PropertyData.
  • Then, pass in the entityData object to the Create function.
  • Call Helper function to assign back the returned results from the Entity service.
    
    

• Add code in <Retrieve> button. Click the button to retrieve item information by assigning the key value ItemCode and passing in the entityData object to the Retrieve function.
  
  
   
• Add code in <Update button>. Click the button to update a specific item by assigning all the text box values into the specific item’s property, and then passing in the entityData object to the Update function.
  
  
   
• Add code in <Delete> button. Click the button to update a specific item by assigning the key value, and then passing in the entityData object to the Delete function.
  
  
   
• Add code in <OpenNew> button. Click the button to retrieve the default values by passing in the entityData object to the OpenNew function.
  
  

• Add code in <Validate> button. Click the button to validate the data entered by assigning all the text box values into the specific item’s property, and then passing in the entityData object to the Validate function. 
  
  

• Add code in <Save> button. Click the button to save an item by:
  • Assigning all the text box values into PropertyData.
  • Then, pass in the entityData object to the Save function. The item will be created if it does not exist. Otherwise, the data for the item will be updated.
  • Use the Helper function to assign back the returned results from the entity service.
    
    

9. You can also add a Try-Catch statement to catch the exception during the CRUD operations.

For example,

Try

…….

Catch ex As Exception

MessageBox.Show("Error Occurred :" & ex.Message, "Entity Error", MessageBoxButtons.OK, MessageBoxIcon.Error)

End Try 

If there is a validation error during the operation, an error message will be displayed, as shown in the following: