Windows Communications Foundation (WCF)™-Based Components

What Is WCF?

.NET Developer

Role	Knowledge Base	Responsibilities
.NET Developer	Little to no MATLAB experience Moderate IT experience .NET expert Minimal access to IT systems	Integrates deployed component with the rest of the .NET application

The Windows Communication Foundation™ (or WCF) is an application programming interface in the .NET Framework for building connected, service-oriented, Web-centric applications.

WCF supports distributed computing using a service-oriented architecture. Clients consume multiple services that can be consumed by multiple clients. Services are loosely coupled to each other.

Services typically have a WSDL interface (Web Services Description Language), which any WCF client can use to consume the service, regardless of which platform the service is hosted on.

A WCF client connects to a WCF service via an endpoint. Each service exposes its contract via one or more endpoints. An endpoint has an address, which is a URL specifying where the endpoint can be accessed, and binding properties that specify how the data will be transferred.

What's the Difference Between WCF and .NET Remoting?

You generate native .NET objects using .NET Remoting and native .NET types using WCF.

What's the difference between these two technologies and which should you use?

WCF is an end-to-end Web Service. Many of the advantages afforded by .NET Remoting—a wide selection of protocol interoperability, for instance—can be achieved with a WCF interface, in addition to having access to a richer, more flexible set of native data types. .NET Remoting can only support native objects.

WCF offers more robust choices in most every aspect of Web-based development, even implementation of a Java client, for example.

For More information About WCF

For up-to-date information regarding WCF, refer to the MSDN article "Windows Communication Foundation."

Back to Top

Before Running the WCF Example

Before running this example, keep the following in mind:

• You must be running at least Microsoft .NET Framework 3.5 to use the WCF feature.

• If you want to use WCF, the easiest way to do so is through the type-safe API. Therefore, you should be familiar with the Type-Safe Interface Generation and Implementation section before attempting to run the WCF example.

• WCF and .NET Remoting are not compatible in the same deployment project or component.

• The example in this chapter requires both client and server to use message sizes larger than the WCF defaults. For information about changing the default message size, see the MSDN article regarding setting of the maxreceivedmessagesize property.

Back to Top

Deploying a WCF-Based Component

Deploying a WCF-based component requires the expertise of a .NET Developer (see description of .NET Developer) because it requires performing a number of advanced programming tasks.

 Where To Find Example Code

To deploy a WCF-based component, follow this general workflow:

1. Write and Test Your MATLAB Code

2. Develop Your WCF Interface

3. Build Your Component and Generate Your Type-Safe API

4. Develop Server Program Using the WCF Interface

5. Compile the Server Program

6. Run the Server Program

7. Generate Proxy Code for Clients

8. Compile the Client Program

9. Run the Client Program

Write and Test Your MATLAB Code

Create your MATLAB program and then test the code before implementing a type-safe interface. The functions in your MATLAB program must match the declarations in your native .NET interface.

In the following example, the deployable MATLAB code contains one exported function, addOne. The addOne function adds the value one (1) to the input received. The input must be numeric, either a scalar or a matrix of single or multiple dimensions.

function y = addOne(x)
% ADDONE Add one to numeric input. Input must be numeric.

    if ~isnumeric(x)
        error('Input must be numeric. Input was %s.', class(x));
    end
    y = x + 1;

end

Note   addOne must perform run-time type checking to ensure valid input.

Develop Your WCF Interface

After you write and test your MATLAB code, develop an interface in either C# or Visual Basic that supports the native types through the API.

Define IAddOne Overloads.  See Develop Your Interface Using Native .NET Types for complete rules on defining interface overloads.

In addition, when using WCF, your overloaded functions must have unique names.

Note that in the WCF implementation of addOne, you decorate the methods with the OperationContract property. You give each method a unique operation name, which you specify with the Name property of OperationContract, as in this example:

using System.ServiceModel;

[ServiceContract]
public interface IAddOne
{
    [OperationContract(Name = "addOne_1")]
    int addOne(int x);

    [OperationContract(Name = "addOne_2")]
    void addOne(ref int y, int x);

    [OperationContract(Name = "addOne_3")]
    void addOne(int x, ref int y);

    [OperationContract(Name = "addOne_4")]
    System.Double addOne(System.Double x);

    [OperationContract(Name = "addOne_5")]
    System.Double[] addOne(System.Double[] x);

    [OperationContract(Name = "addOne_6")]
    System.Double[][] addOne(System.Double[][] x);
}

As you can see, the IAddOne interface specifies six overloads of the addOne function. Also, notice that all have one input and one output (to match the MATLAB addOne function), though the type and position of these parameters varies.

For additional code snippets and data conversion rules regarding type-safe interfaces, see Develop Your Interface Using Native .NET Types.

For more information on WCF contracts and properties, see the Microsoft WCF Web Site.

Compile IAddOne into an Assembly.  Compile IAddOne.cs into an assembly using Microsoft Visual Studio.

Note   This example assumes your assembly contains only IAddOne. Realistically, it is more likely that IAddOne will already be part of a compiled assembly. The assembly may be complete even before the MATLAB function is written.

Build Your Component and Generate Your Type-Safe API

Use either the Deployment Tool (deploytool) or the deployment command line tools to generate the type-safe API.

Using the Deployment Tool.  The Deployment Tool generates the type-safe API, when you build your component, if the correct options are selected in the Settings dialog box.

1. Create your Deployment Tool project. Follow the steps in Deployable Component Creation in the Getting Started chapter of this user's guide.

   When defining your project, use these values:

   Project Name	AddOneComp
   Class Name	Mechanism
   File to compile	addOne

   Note   Do not click the Build button at this time.

2. Click the Actions ( ) button.

3. Select Settings.

4. On the Type-Safe API tab, do the following:

   1. Select Enable Type-Safe API.

   2. In the Interface assembly field, specify the location of the type-safe/WCF interface assembly that you built.

   3. Select IAddOne from the .NET interface drop-down box. The interface name is usually prefixed by an I.

      Tip   If the drop-down is blank, the Deployment Tool may have been unable to find any .NET interfaces in the assembly you selected. Select another assembly.

   4. Specify Mechanism, as the class name you want the generated API to wrap, in the Wrapped Class field.

   5. Click Close to dismiss the Settings dialog box.

   Note   Leave the Namespace field blank.

5. Build the project as usual by clicking the Build button.

Using the Deployment Command-Line Tools.  To generate the type-safe API with your component build (compilation) using mcc, do the following:

1. Build the component by entering this command from MATLAB:

   mcc -v -B 'dotnet:AddOneComp,Mechanism,3.5,private,local'
                                                     addOne
   

   See the mcc reference page in this user's guide for details on the options specified.

2. Generate the type-safe API by entering this command from MATLAB:

   ntswrap -c AddOneComp.Mechanism -i IAddOne -a IAddOne.dll

   where:

   • -c specifies the namespace-qualified name of the MATLAB Builder NE component to wrap with a type-safe API. If the component is scoped to a namespace, specify the full namespace-qualified name (AddOneComp.Mechanism in the example). Because no namespace is specified by ntswrap, the type-safe interface class appears in the global namespace.

   • -i specifies the name of the .NET interface that defines the type-safe API. The interface name is usually prefixed by an I.

   • -a specifies the absolute or relative path to the assembly containing the .NET statically-typed interface, referenced by the -i switch.

     Tip   If the assembly containing the .NET interface IAddOne is not in the current folder, specify the full path.

   Caution   Not all arguments are compatible with each other. See the ntswrap reference page in this user's guide for details on all command options.

Develop Server Program Using the WCF Interface

You have now built your component and generated a WCF-compliant type-safe API.

Next, develop a server program that provides access (via the WCFServiceContract) to the overloads of addOne defined by the WCF IAddOne interface. The program references an App.config XML configuration file.

The WCF server program loads the WCF-based addOne.Mechanism component and makes it available to SOAP clients via the type-safe mechanismIAddOne interface.

About Jagged Array Processing   When writing your interface, you will be coding to handle jagged arrays, as opposed to rectangular arrays. For more information about jagged arrays, see Jagged Array Processing in Component Integration in this user's guide.

 WCF Server Program

using System;
using System.Text;
using System.ServiceModel;


namespace AddMasterServer
{
    class AddMasterServer
    {
        static void Main(string[] args)
        {
            try
            {
                using (ServiceHost host = 
                    new ServiceHost(typeof(MechanismIAddOne)))
                {
                    host.Open();
                    Console.WriteLine("
                       AddMaster Server is up running......");
                    Console.WriteLine("
                       Press any key to close the service.");
                    Console.ReadLine();
                    Console.WriteLine("Closing service...");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }  
        }
    }
}

 App.config XML file

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.web>
    <compilation debug="true" />
  </system.web>
  <system.serviceModel>
    <services>
      <service behaviorConfiguration=
       "AddMaster.ServiceBehavior" name="MechanismIAddOne">
        <endpoint
          address=""
          binding="wsHttpBinding"
          contract="IAddOne"
          name="HttpBinding" />
        <endpoint
        address=""
        binding="netTcpBinding"
        contract="IAddOne"
        name="netTcpBinding" />
        <endpoint
          address="mex"
          binding="mexHttpBinding"
          contract="IMetadataExchange"
          name="MexHtppBinding"/>
        <endpoint
        address="mex"
        binding="mexTcpBinding"
        contract="IMetadataExchange"
        name="MexTCPBinding"/>
        <host>
          <baseAddresses>
           <add baseAddress=
                "http://localhost:8001/AddMaster/" />
           <add baseAddress=
                "net.tcp://localhost:8002/AddMaster/" />
          </baseAddresses>
        </host>
      </service>
    </services>
    <behaviors>
      <serviceBehaviors>
        <behavior name="AddMaster.ServiceBehavior">
          <serviceMetadata httpGetEnabled="True" httpGetUrl=
                     "http://localhost:8001/AddMaster/mex" />
          <!-- To receive exception details in faults for
          <!--  debugging purposes, 
          set the value below to true.  Set to false before
          deployment to avoid disclosing exception 
          information -->
          <serviceDebug includeExceptionDetailInFaults="True" />
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>
</configuration>

Compile the Server Program

Compile the server program using Microsoft Visual Studio by doing the following:

1. Create a Microsoft Visual Studio project named AddMaster.

2. Add AddMasterServer.cs and App.config (the configuration file created in the previous step) to your project.

3. Add references in the project to the following files.

   This reference:	Defines:
   IAddOne.dll	The .NET native type interface IAddOne
   MechanismIAddOne.dll	The generated type-safe API
   AddOneCompNative.dll	The MATLAB Builder NE component

   Note   Unlike other .NET deployment scenarios, you do not need to reference MWArray.dll in the server program source code. The MWArray data types are hidden behind the type-safe API in MechanismIAddOne.

4. If you are not already referencing System.ServiceModel, add it to your Visual Studio project.

5. Compile the program with Microsoft Visual Studio.

Run the Server Program

Run the server program from a command line.

The output should look similar to the following.

AddMaster Server is up running......
Press any key to close the service.

Pressing a key results in the following.

Closing service....

Generate Proxy Code for Clients

Configure your clients to communicate with the server by running the automatic proxy generation tool, svcutil.exe. Most versions of Microsoft Visual Studio can automatically generate client proxy code from server metadata.

Caution   Before you generate your client proxy code using this step, the server must be available and running. Otherwise, the client will not find the server.

1. Create a client project in Microsoft Visual Studio.

2. Add references by using either of these two methods. See Port Reservations and Using localhost 8001 for information about modifying port configurations.

   Method 1

   Method 2

   In the Solutions Explorer pane, right-click References. Select Add Service Reference. The Add Service Reference dialog box appears. In the Address field, enter: http://localhost:8001/ AddMaster/ Note   Be sure to include the / following AddMaster. In the Namespace field, enter AddMasterClient. Click OK.

   Enter the following command from your client application directory to generate AddMasterProxy.cs, which contains client proxy code. This command also generates configuration file App.config. svcutil.exe /t:code http://localhost:8001 /AddMaster/ /out:AddMasterProxy.cs /config:App.config Note   Enter the above command on one line, without breaks. Add AddMasterProxy.cs and App.config to your client project

Port Reservations and Using localhost 8001.  When running a self-hosted application, you may encounter issues with port reservations. Use one of the tools below to modify your port configurations, as necessary.

Compile the Client Program

The client program differs from the AddMaster.cs server program as follows:

• At start-up, this program connects to the AddMasterService provided by the AddMaster WCF service.

• Instead of directly invoking the methods of the type-safe mechanism IAddOne interface, the WCF client uses the method names defined in the OperationContract attributes of IAddOne.

Compile the client program by doing the following:

1. Add the client code (AddMasterClient.cs) to your Microsoft Visual Studio project.

2. If you are not already referencing System.ServiceModel, add it to your Visual Studio project.

3. Compile the WCF client program in Visual Studio.

    WCF Client Program

   using System;
   using System.Text;
   using System.ServiceModel;
   
   namespace AddMasterClient
   {
       class AddMasterClient
       {
           static void Main(string[] args)
           {
               try
               {
                   // Connect to AddMaster Service
                   Console.WriteLine("Conntecting to 
                           AddMaster Service through 
                           Http connection...");
                   AddOneClient AddMaster = 
                           new AddOneClient("HttpBinding");
                   Console.WriteLine("Conntected to 
                                      AddMaster Service...");
   
                   // Output as return value
                   int one = 1;
                   int two = AddMaster.addOne_1(one);
                   Console.WriteLine("addOne({0}) = {1}", 
                                                   one, two);
   
                   // Output: first parameter
                   int i16 = 16;
                   int o17 = 0;
                   AddMaster.addOne_2(ref o17, i16);
                   Console.WriteLine("addOne({0}) = {1}", 
                                                  i16, o17);
   
                   // Output: second parameter
                   int three = 0;
                   AddMaster.addOne_3(two, ref three);
                   Console.WriteLine("addOne({0}) = {1}", 
                                                 two, three);
   
                   // Scalar doubles
                   System.Double i495 = 495.0;
                   System.Double third = 
                                    AddMaster.addOne_4(i495);
                   Console.WriteLine("addOne({0}) = {1}", 
                                               i495, third);
   
                   // Vector addition
                   System.Double[] i = { 30, 60, 88 };
                   System.Double[] o = AddMaster.addOne_5(i);
                   Console.WriteLine(
                        "addOne([{0} {1} {2}]) = [{3} {4} {5}]",
                            i[0], i[1], i[2], o[0], o[1], o[2]);
               }
               catch (Exception ex)
               {
                   Console.WriteLine(ex.Message);
               }
               
               Console.WriteLine("Press any key to close 
                                 the client application.");
               Console.ReadLine();
               Console.WriteLine("Closing client...");    
           }
       }
   }

Run the Client Program

Run the client program from a command line.

The output should be similar to the following:

Conntecting to AddMaster Service through Http connection...
Conntected to AddMaster Service...
addOne(1) = 2
addOne(16) = 17
addOne(2) = 3
addOne(495) = 496
addOne([30 60 88]) = [31 61 89]
addOne([0 2; 3 1]) = [1 3; 4 2]
Press any key to close the client application.

Pressing a key results in the following.

Closing client....

Back to Top

Type-Safe Interface Generation and Implementation

Managed Extensibility Framework (MEF) Plug-Ins

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit