Documentation

Create Windows Communications Foundation Based Components

Before Running the 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.

  • 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.

Deploying a WCF-Based Component

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

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

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 Implement a Type-Safe Interface 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 Implement a Type-Safe Interface.

For up-to-date information regarding WCF, see What Is Windows Communication Foundation on Microsoft webpage.

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 Library Compiler app or the deployment command line tools to generate the type-safe API.

Using the Library Compiler.  The Library Compiler app generates the type-safe API, when you build your component, if the correct options are selected.

  1. Create your project.

    When defining your project, use these values:

    Project NameAddOneComp
    Class NameMechanism
    File to compileaddOne

    Note

    Do not click the Package button at this time.

  2. Expand the Additional Runtime Settings section.

  3. 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 Library Compiler app 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.

    Note

    Leave the Namespace field blank.

  4. Build the project as usual by clicking the Package 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 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 Compiler SDK™ assembly 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 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 this documentation.

 WCF Server Program

 App.config XML file

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.dllThe .NET native type interface IAddOne
    MechanismIAddOne.dllThe generated type-safe API
    AddOneCompNative.dllThe generated assembly

    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 1Method 2
    1. In the Solutions Explorer pane, right-click References.

    2. Select Add Service Reference. The Add Service Reference dialog box appears.

    3. In the Address field, enter: http://localhost:8001/AddMaster/

      Note

      Be sure to include the / following AddMaster.

    4. In the Namespace field, enter AddMasterProxy.

    5. Click OK.

    1. 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.

    2. 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.

if You Run....Use This Tool to Modify Port Configurations....
Windows® XPhttpcfg
Windows Vista™netsh
Windows 7netsh

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

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....