Generated code - WebAPI / WCF / XML Webservices support

Preface

One hot buzzword of the last couple of years has to be 'webservices', which is short for XML Webservices, i.e.: XML message based services offered through a normal HTTP based website. As webservices are XML based, the .NET framework uses XmlSerializer to produce XML which reflects the objects returned from a webmethod and to produce instances of classes from the XML received, for example at the client. This section describes how to use the entity and entity collection classes of the generated code in a webservice scenario. Every entity and entity collection class implements IXmlSerializable, which makes it possible to transparently use these classes with webmethods, without the necessity to first produce XML from them using their WriteXml() methods.

The preferred way to implement webservices and .NET is by using WebAPI, or the more low level variant WCF (Windows Communication Foundation). LLBLGen Pro entities are fully usable with WebAPI and WCF similar to webservices. By default, LLBLGen Pro entity classes aren't marked with DataContract and DataMember attributes. If you want to have these defined, use the LLBLGen Pro designer's attribute feature to define the DataContract and DataMember attributes on entities and fields. Define these attributes in the Project Settings of the LLBLGen Pro designer. A step-by-step guide is given below in the WebAPI section.

WebAPI

To write a WebAPI using LLBLGen Pro, you can use any query API we support: Linq, QuerySpec or the low-level API, if you're going to return IEnumerable entities. By default, WebAPI serializes the data to XML, though you can opt for JSON if you want to. The following steps, make sure that your entities are properly serialized from a WebAPI in XML or JSON.

Decorating elements with DataContract and DataMember attributes.

To decorate fields, entities and navigators with the proper attributes, please follow these steps:

• Load your LLBLGen Pro project into the LLBLGen Pro Designer and select from the main menu Project -> Settings. A dialog opens. Navigate to General -> Conventions -> Code Generation -> Attributes.
• At the top, 'Entity' is selected. Add below Attribute definition: DataContract
• Press enter.
• Select at the top 'NormalField'. Add below Attribute definition: DataMember
• Press enter.
• Repeat the action you did with NormalField also for NavigatorSingleValue and NavigatorCollection.
• Click OK to close the settings dialog. You have now decorated all entities, the fields of the entities and the navigator properties with the required attributes.
• Regenerate your code.

You now have entities which are decorated with the right attributes and which are serializable from the WebAPI interface you're writing. To start with a WebAPI, simply follow one of the many tutorials given at the main WebAPI site. LLBLGen Pro doesn't come with a scaffolding add-in like Entity Framework does, but in general you'd want to start with an empty WebAPI service anyway.

An example of a WebAPI method, which returns all products together with the category entities pre-fetched:

public IEnumerable<ProductEntity> GetAllProducts()  
{  
    using(var adapter = new DataAccessAdapter())  
    {  
        var metaData = new LinqMetaData(adapter);  
        return metaData.Product.WithPath(p=>p.Prefetch(x=>x.Category)).ToList();       
    }  
}  

JSON support

Now, you might think that with the DataContract/DataMember attributes, it's ok to use the DataContractJsonSerializer, but that's not the case. Instead, we're going to use the default JSON serializer of WebAPI, which is the Newtonsoft JSON.NET serializer. By default it doesn't do what we want, so we have to configure it. However this is very simple:

Open WebApiConfig.cs which is located in the App_Start folder. Now add the following lines to the Register method:

var json = config.Formatters.JsonFormatter;  
json.SerializerSettings.PreserveReferencesHandling = Newtonsoft.Json.PreserveReferencesHandling.Objects;  
json.SerializerSettings.ContractResolver = new DefaultContractResolver()   
    {   
        IgnoreSerializableInterface = true,   
        IgnoreSerializableAttribute = true   
    }; 
	

After this, your entities will serialize to JSON as expected. The above example method will, after using the configuration as describe above, serialize the data to JSON, including reference tracking. Pulling the data as XML by specifying application/xml in the Accept header element of the request will make things fail as WebAPI chooses a DataContract serializer by default if it sees a [DataContract] attribute on the objects to serialize. This is OK, as both sides have to work with the entity data anyway, so mutual agreement of what's sent is required.

Service related XML Serialization information

For web services and WCF, which both use the IXmlSerializable implementations of the entity and entity collection classes, LLBLGen Pro uses its own Compact25 format, which is very lightweight and very fast to consume and produce as it contains almost no overhead. See for a description of the Compact25 format: generated code - Xml support.

Example usage

The example discussed here is pretty simple. It offers a service with three methods: GetCustomer, SaveCustomer and GetCustomers. The client consumes the service to retrieve a customer to have it edited in a winforms application and saves the changed data back into the database using the webservice, plus it uses the service to display all customers available.

The service project has references to both generated projects: the database generic and the database specific project. The client only has a reference to the database generic project, as it uses the service for database specific activity, namely the persistence logic to work with the actual data. Because both client and service have references to the database generic project, they both can use the same types for the entities, in this case the CustomerEntity.

The code below uses our low-level API, but you can also use Linq to LLBLGen Pro or QuerySpec to fetch the entities. The GetCustomers method returns a non-generic EntityCollection object as webservices can't deal with generics.

The service

// C#
[WebService(Namespace="http://www.llblgen.com/examples")]
public class CustomerService : System.Web.Services.WebService
{
	[WebMethod]
	public CustomerEntity GetCustomer(string customerID)
	{
		CustomerEntity toReturn = new CustomerEntity(customerID);
		using(DataAccessAdapter adapter = new DataAccessAdapter())
		{
			adapter.FetchEntity(toReturn);

			return toReturn;
		}
	}

	[WebMethod]
	public EntityCollection GetCustomers()
	{
		EntityCollection customers = new EntityCollection(new CustomerEntityFactory());
		using(DataAccessAdapter adapter = new DataAccessAdapter())
		{
			adapter.FetchEntityCollection(customers, null);
			return customers;
		}
	}

	[WebMethod]
	public bool SaveCustomer(CustomerEntity toSave)
	{
		using(DataAccessAdapter adapter = new DataAccessAdapter())
		{
			return adapter.SaveEntity(toSave);
		}
	}
}

' VB.NET
<WebService(Namespace="http://www.llblgen.com/examples")> _
Public Class CustomerService 
	Inherits System.Web.Services.WebService

	<WebMethod> _
	Public Function GetCustomer(customerID As String) As CustomerEntity
		Dim toReturn As New CustomerEntity(customerID)
		Dim adapter As New DataAccessAdapter()
		Try
			adapter.FetchEntity(toReturn)
			Return toReturn
		Finally
			adapter.Dispose()
		End Try
	End Function

	<WebMethod> _
	Public Function GetCustomers() As EntityCollection
		Dim customers As New EntityCollection(New CustomerEntityFactory())
		Dim adapter As New DataAccessAdapter()
		Try
			adapter.FetchEntityCollection(customers, Nothing)
			Return customers
		Finally
			adapter.Dispose()
		End Try
	End Function

	<WebMethod> _
	Public Function SaveCustomer(toSave As CustomerEntity) As Boolean
		Dim adapter As New DataAccessAdapter()
		Try
			Return adapter.SaveEntity(toSave)
		Finally
			adapter.Dispose()
		End Try
	End Function
End Class

Custom Member serialization/deserialization

Windows Communication Foundation (WCF) support

Note:

When sending entities over the wire using WCF, the 'IsNew' flag is not passed along as it is determinable on the service side for new entities. If you use the trick where you set the IsNew flag manually on an entity and then send the entity over the wire to the service, the IsNew flag is set to false at the service during deserialization, so you have to set it back to true in that special case scenario.

Interface with ServiceContract

// C#
[ServiceContract]
[ServiceKnownType(typeof(CustomerEntity))]
[ServiceKnownType(typeof(EntityCollection))]
public interface IWCFExample
{
    [OperationContract]
    IEntity2 GetCustomer(string customerID);

    [OperationContract]
    IEntityCollection2 GetCustomers();
}

' VB.NET
<ServiceContract(), _
ServiceKnownType(GetType(CustomerEntity)), _
ServiceKnownType(GetType(EntityCollection))> _
Public Interface IWCFExample
    <OperationContract()> _
    Function GetCustomer(customerID As String) As IEntity2 
    <OperationContract(&)gt; _
    Function GetCustomers() As IEntityCollection2 
End Interface

Server implementation

// C#
// class to implement the service logic
[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single)]
public class WCFExampleService : IWCFExample
{
    public IEntity2 GetCustomer(string customerID)
    {
        CustomerEntity toReturn = new CustomerEntity(customerID);
        using(DataAccessAdapter adapter = new DataAccessAdapter())
        {
            adapter.FetchEntity(toReturn);
        }
        return toReturn;
    }

    public IEntityCollection2 GetCustomers()
    {
        EntityCollection toReturn = new EntityCollection(new CustomerEntityFactory());
        using(DataAccessAdapter adapter = new DataAccessAdapter())
        {
            adapter.FetchEntityCollection(toReturn, null);
        }
        return toReturn;
    }
}

// class to actually run the service:
public class WCFExampleServerHost
{
    public WCFExampleServerHost()
    {
        WCFExampleService server = new WCFExampleService();
        ServiceHost host = new ServiceHost(server);
        host.Open();
    }
}

' VB.NET
' class to implement the service logic
<ServiceBehavior(InstanceContextMode := InstanceContextMode.Single)> _
Public Class WCFExampleService 
	Implements IWCFExample

    Public Function GetCustomer(customerID As string) As IEntity2 Implements IWCFExample.GetCustomer
        Dim toReturn As new CustomerEntity(customerID)
        Using adapter As New DataAccessAdapter()
            adapter.FetchEntity(toReturn)
        End Using
        Return toReturn
    End Function

    Public Function GetCustomers() As IEntityCollection2 Implements IWCFExample.GetCustomers
        Dim toReturn As New EntityCollection(New CustomerEntityFactory())
        Using adapter As New DataAccessAdapter()
            adapter.FetchEntityCollection(toReturn, Nothing)
        End Using
        Return toReturn
    End Function
End Class

' class to actually run the service:
Public Class WCFExampleServerHost
    Public Sub New()
        Dim server As New WCFExampleService()
        Dim host As New ServiceHost(server)
        host.Open()
    End Sub
End Class

Client usage of the service

// C#
ChannelFactory<IWCFExample> channelFactory =
        new ChannelFactory<IWCFExample>("WCFExampleServer");
IWCFExample server = channelFactory.CreateChannel();

// Fetch an entity
IEntity2 c = server.GetCustomer("CHOPS");

// Fetch a collection
IEntityCollection2 customers = serverTest.GetCustomers();

' VB.NET
Dim channelFactory As New ChannelFactory(Of IWCFExample)("WCFExampleServer")
Dim server As IWCFExample = channelFactory.CreateChannel()

' Fetch an entity
Dim c As IEntity2 = server.GetCustomer("CHOPS")

' Fetch a collection
Dim customers As IEntityCollection2 = serverTest.GetCustomers()

Configuration of the service

<system.serviceModel>
    <bindings>
        <netTcpBinding>
            <binding name="RemoteConfig"
                closeTimeout="infinite"
                openTimeout="infinite"
                sendTimeout="infinite"
                receiveTimeout="infinite"
                maxBufferSize="65536000"
                maxReceivedMessageSize="65536000" />
        </netTcpBinding>
    </bindings>
    <services>
        <service name="Service.WCFExampleServer">
            <endpoint address="" binding="netTcpBinding" name="WCFExampleServer"
                      bindingConfiguration="RemoteConfig"
              contract="Interfaces.IWCFExample" />
            <host>
                <baseAddresses>
                    <add baseAddress="net.tcp://localhost:6543/WCFExampleServer" />
                </baseAddresses>
            </host>
        </service>
    </services>
</system.serviceModel> 

Configuration of the client

<system.serviceModel>
    <bindings>
        <netTcpBinding>
            <binding name="RemoteConfig"
                closeTimeout="infinite"
                openTimeout="infinite"
                sendTimeout="infinite"
                receiveTimeout="infinite"
                maxBufferSize="65536000"
                maxReceivedMessageSize="65536000" />
        </netTcpBinding>
    </bindings>
    <client>
        <endpoint address="net.tcp://localhost:6543/WCFExampleServer"
                  name="WCFServer" binding="netTcpBinding"
                  bindingConfiguration="RemoteConfig"
                  contract="Interfaces.IWCFExample" />
    </client>
</system.serviceModel>