Series 1. DotNetNuke and WCF
Agenda/Intro:
•Why use WCF with DotNetNuke?
•Quick Look at WCF
•Demos / code examples
–Monitoring your web site
–Offline management of your content
•Questions
OK, so now let’s take a quick look at WCF and talk about the components of a WCF service.
When adding a WCF Service to your DotNetNuke web site, Visual Studio will generate 4 components for you.
1. The service file which identifies the service and tells IIS where the service source is located. Using a post office metaphor, think of this as the street address that identifies where your house is located. It’s not exactly a perfect metaphor, the actual ‘address’ of your service will be defined in the configuration file, but it is the URL through which your service will be accessed.
2. The service interface file which defines the service, operation and data contracts. Furthering the metaphor, think of the interface as the people who live in your house who can receive messages.
3. The implementation file which is where you write your service’s functional code. The code that will do the work in response to receiving a message.
4. The configuration. Entries in your web.config file.
Let’s take a closer look. In this example, I will start with an ‘out-of-the-box’ DotNetNuke, I created the site using the 5.1.4 Starter Kit. To begin, right-click on the Solution file and select “Add New Item…”
Select WCF service from the list of available items and give your service a name. In this example, I’ve entered DNNService as the service name. Select ‘Visual Basic’ as the Language name and click the Add button.
When you click the Add button, Visual Studio will add three new files to your solution, DNNService.svc which will be placed in the root folder of your web site, and IDNNService.vb and DNNService.vb will be created in your App_Code folder, which are the Interface file and the Implementation file, respectively. So, let’s take a look at each of the components.
The service file:
DNNService.svc is a very simple file that just has a single ServiceHost directive
1: <%@ ServiceHost Language="VB" Debug="true" Service="DNNService"
2: CodeBehind="~/App_Code/DNNService.vb" %>
This file specifies the Service name, “DNNService”, and where the code behind is located.
The Interface file:
Ok, so now we’re going to get into the meaty part of the session. The interface file, “IDNNService” is where you define your service “contracts”. Contracts are use to define what functions (methods) are available through this service, and what data (parameters) it expects for exposed functions.
It is a standard interface file. The only difference is that you apply the ServiceContract attribute
1: Imports System.ServiceModel
2: Imports System.ServiceModel.Web
3:
4: <ServiceContract()> _
5: Public Interface IDNNService
6:
7: End Interface
At this point we need to decide what functionality we want to expose through our service. Remember, I said a WCF service is used to expose data and/or functionality. In this first simple example, we’ll do the obligatory ‘Hello World’ demo, just so that you can understand the basic concepts of a WCF service. We’ll expose a method named “SayHello”, expect to get a string parameter in, and send back a string as the result. In order to expose a function, we just write the function declaration and add an OperationContract attribute
1: Imports System.ServiceModel
2: Imports System.ServiceModel.Web
3:
4: <ServiceContract()> _
5: Public Interface IDNNService
6:
7: <OperationContract()> _
8: Function SayHello(ByVal s As String) As String
9:
10: End Interface
On line 8 we define our function and on line 7 we specify the OperationContract attribute. So far so good. We can now move on to our Implementation file to write the actual code to do the work.
The Implementation file:
We’ve defined our ServiceContract, and a single OperationContract, now we need to write the code to implement that Operation. The “DNNService.vb” file is where we do that. We have a public class, “DNNService” that Implements the “IDNNService” interface, Now we need to add the function that we prototyped in our interface file.
1: Imports System.Collections.Generic
2: Imports DotNetNuke.Entities.Modules
3:
4: Public Class DNNService
5: Implements IDNNService
6:
7: Public Function SayHello(ByVal s As String) As String _
8: Implements IDNNService.GetMetrics
9:
10: Return String.Format("Hello {0}", s)
11:
12: End Function
13:
14: End Class
We indicate on line 5 above that this SayHello function implements the IDDNService.SayHello OperationContract, then simply write the code to take the incoming parameter, “s”, and output a concatenated string.
That’s it. That’s all we need to do to define a ServiceContract, an OperationContract and then implement that Contract with some code in our implementation file.
So, let’s test it out!. I create a Test project, and add a ServiceReference to our brand new
DNNService”. Right-clicking on the Reference section of my Test project, I select “Add Service Reference…”
In the Add Service Reference Dialog, we can browse to our DNNService.svc file, or simply hit the Discover button to find all services defined within our current solution. You can see the Service, the interface and the operation contract in the dialog, we name our reference “DNNServiceReference” and hit OK to add the reference.
Now, let’s write a Unit test to test out our SayHello service method.This test will create a proxy to access our service, call the SayHello method passing the text “DNN Programmers” as the input string, and expects to receive “Hello DNN Programmers” in return.
1: Public Sub Test_SayHello_Function()
2:
3: Using proxy As New DNNServiceReference.DNNServiceClient()
4: Dim results = proxy.SayHello("DNN Programmers")
5: Assert.AreEqual("Hello DNN Programmers", results)
6: End Using
7:
8: End Sub
We run the test…
and it passed! Our WCF service works!
So, to review. We defined a WCF service named DNNService and added it to our DotNetNuke web site, we defined the ServiceContract and a single OperationContract, wrote the code to implement the OperationContract, and finally wrote a simple unit test to make sure our service worked.
In the next part, I will show you how to expose an additional endpoint (door) into our service. I’ll walk you through adding a REST endpoint and demonstrate accessing our sample SayHello method using IE as the client and accessing our service through a RESTful URI.
Next: Adding a REST endpoint to our service