This was originally published on Dec-03-2013
This assumes that you have the basic idea behind what a service is and the high level design assumptions. Basically that you understand that a service is a contract between the service provider to the consumer. The contract is internally represented as an interface and that the service can then be exposed and consumed using different mechanisms (transport, address, etc.) known as endpoints. In this exercise we will create a basic service that takes a caller’s name are gives them a user friendly message indicating the current system date and time.
Create a new service library project
- Create new project, use WCF / Service Library template as shown below.
- Delete the Service1.cs and IService1.cs that get created by default.
- Now let us get to create our service to provide the current system date and time as string. This service will take the requester’s name as an input parameter and return a friendly message with the current system date and time.
- Create a new Class called CurrentTime for the message contract as shown below and annotate it with [DataContract]. You will have to import the System.Runtime.Serialization namespace to resolve the [DataContract].
- Next we will decide which fields to include in the data contract and annotate those with the [DataMember] attribute. Since we have only one field, “RequestersName”, that is what we will annotate.
- Now, we will add a service contract to work with the Data Contract. So, let us add a new interface called, ICurrentTimeService.cs and add it to the project.
- In here, we will define our contract operations. In our case, we simply want to provide the user with a way to get the current date and time, so we shall call this GetCurrentTime as shown below. For WCF to understand this as a service contract, we will annotate the ICurrentTimeService interface with [ServiceContract]. For ServiceContract to be recognized, you will need to reference the System.ServiceModel namespace.
- Next we need to tell WCF which methods (operations) in our service contract we wish to include. We do this by annotating the method definition with [OperationContract]. Since we have only 1 operation, GetCurrentTime, we will go ahead and annotate it as such.
- Next we will add the actual implementation of the Service Contract described above. To do this, let us create a new class called CurrentTimeService that implements ICurrentTimeService as shown below.
- We will also implement the GetCurrentTime method in the service to actually return a friendly message with the current date and time.
- Next, we will describe some service behavior for our service implementation. To do this, we will annotate the service class, the CurrentTimeService class with [ServiceBehavior(…)] attribute to specify how our service will be managed by the WCF framework runtime. We will specify the following:
- ServiceBehavior(InstanceContextMode=InstanceContextMode.PerCall) to Single. We could have also specified as Single (much like a singleton) or PerSession (create once per user (could be calling application) session. This will cause the WCF runtime to create only a single instance of our service at runtime for each call.
- Now, how do we communicate with our new service? To do this we have to create an endpoint that represents a particular character set on how we are to communicate with our service.
- Now, we shall visit our friend, the WCF App.Config file which is already created for us.
- Right-click on the App.config file and choose, Edit WCF Configuration.
- In the modal dialog that appears, start from the top left, Services, and click on the first service, select it in the right hand pane and click on the … elipses to locate our service implementation, TutorialService.CurrentTimeService under Bin\Debug as shown in the diagram below. (Note, if you don’t find anything under Bin\Debug, make sure you build your project).
- Next, expand the service to locate the endpoints, expand the endpoints tree and choose the first empty endpoint. Select the Contract in the right hand pane of the dialog box, click on the … elipses and browse to Bin\Debug and select the contract interface as shown below.
- Next, let us look at the metadata exchange endpoint. Click on the main Services node locate, on the right pane, notice the metadata exchange endpoint denoted by the address: mex as shown below.
- Now, it is time to test the service. Hit F5 and the WCF Test Client will be launched that you can use to test your newly created service as shown below.
Configuring and Hosting your service
Endpoints, endpoints and endpoints. Here we will cover some different ways you can configure the endpoints for your services.
Here we will discuss how to configure the service endpoints for different forms of communications. As discussed in the previous post on WCF, configurations are managed through the app.config for the service project. In the previous post, we have seen how we can right-click on the app.config and then click on ‘Edit WCF Configuration’ to configure your service, endpoints and behavior.
If we were to examine the app.config by opening it as an XML document, we will find that after completing the last exercise, we have 2 endpoints. One for the basic http deployment and the other for the metadata exchange.
Each endpoint has three attributes associated with it.
- Address – the network address, where is the service located
- Binding – how are we going to communicate with the service such as transport and WS* protocols
- Contract – describes what the message must provide and contain (types and operations).
Below the endpoints definition, in the app.config there is also a <host><baseAddresses><add baseAddress=”….”>… defined that is the base address for all our services that have been defined. The address attribute of an endpoint simply gets added to the base address.
You can add additional endpoints, such as those using another communication protocol such as TCP or Named Pipes, to your service through the Microsoft Service Configuration Editor Dialog box, after you have deployed your service. You can even make these changes directly in your app.config.
Configuring Service Behaviors
We can add different behaviors to our services. For instance you can expose the WSDL / metadata of your service through a Http Get operation by enabling that behavior.
- Create the behavior. In the Microsoft Service Configuration Editor Dialog box, Advanced, Service Behaviors and adding or editing an existing behavior. I have marked the HttpGetEnabled to True, provided a URL for the HttpGetUrl attribute and named it Metadata.
- Use the behavior. Now in the Services node, I locate the service and provide the behavior called Metadata to the BehaviorConfiguration attribute and saved the dialog box.
- Upon hosting the service, the WSDL will now be available at the URL provided in Step 1 above. A client can then generate a proxy from this WSDL.
Configuring Service Bindings
We can also configure bindings for our services to support the various WS* extensions such as Security, Reliable Messaging, etc. To do this, the easiest way is to use the Microsoft Service Configuration Editor Dialog box, go to the Bindings node, right-click and add or edit the appropriate binding and then go to your service endpoint, and in the General pane on the right, associate the binding configuration you just created for the BindingConfiguration attribute.
Hosting your service in IIS
- Start by adding a new Web Site project to the solution.
- Choose the WCF Template and we’ll call it the GetCurrentTimeSite
- Now, delete the Service.cs and IService.cs from the newly created Web Site project and Add a REFERENCE to the web service project.
- This will add the service library dll in the Bin directory.
- Next rename the Service.svc to something more meaningful such as GetCurrentTime.svc
- Next edit the .svc file and change the Service attribute to the fully qualified name, in our case, TutorialService.CurrentTimeService
- Further, delete the codebehind attribute and its value.
- Now, we need to configure the service and its endpoint(s). Launch the web.config Microsoft Service Configuration Editor Dialog box for the web site,
- For the Services node, click on Create a new Service and provide it the service implementation and the contract interface by browsing to the dll in the Bin folder from within the wizard.
- Now test this out by right-clicking on the .svc file and selecting View in Browser.
- You will see the documentation for the newly created service in a browser window.
- To test, go to a command prompt and type in> wcftestclient [address of the service from the documentation. should end in .svc]
- If all works well, go to the IIS management tool and create a new application under one of the sites.
- Now map this new application to a physical path of the service site (GetCurrentTimeSite) in our case.
- Now your service should be available, hosted within IIS.