You can connect an MDriven client application to a remote persistence layer, such as MDrivenServer, over Web API instead of WCF by configuring a PersistenceMapperWEBAPIClient and exposing an MDrivenPersistenceController<T> on the server.

What Web API does

The persistence mapper is the component that carries persistence communication between an application's EcoSpace and its remote persistence layer. PersistenceMapperWEBAPIClient is the Web API implementation of that communication. It performs the same role as PersistenceMapperWCFClient, but uses Web API transport and defaults to HTTPS.

Use Web API when your client and server communicate through a Web API endpoint rather than a WCF .svc endpoint. This also avoids a dependency on WCF in environments where WCF is no longer the preferred technology.

For client capabilities such as model-checksum comparison and a server closed for business message, see Documentation:PersistenceMapperWEBAPIClient.

Switch an existing client from WCF

Replace the WCF persistence mapper with a PersistenceMapperWEBAPIClient. The key changes are:

Configuration item	WCF client	Web API client
Client type	PersistenceMapperWCFClient	PersistenceMapperWEBAPIClient
Endpoint shape	https://YourServerMDrivenServer/APP_A0/A0_PMPWCF.svc	https://YourServerMDrivenServer/api/A0_WebApi
User-name property	WCFServerUserName	ServerUserName
Password property	WCFServerPassword	ServerPassword

1. Ensure that the server exposes the Web API controller described in Create the server endpoint.
2. Create a PersistenceMapperWEBAPIClient in the client application.
3. Set its Uri to the Web API endpoint.
4. Set ServerUserName and ServerPassword to the MDrivenServer credentials used by the application.
5. Assign the mapper to the EcoSpace PersistenceMapper property.
6. Remove or stop assigning the previous WCF mapper.

WCF configuration before migration

yourEcoSpace.PersistenceMapper = persistenceMapperWCFClient;
persistenceMapperWCFClient.Uri = "https://YourServerMDrivenServer/APP_A0/A0_PMPWCF.svc";
persistenceMapperWCFClient.WCFServerUserName = "SomeMDrivenServerUser";
persistenceMapperWCFClient.WCFServerPassword = "'''*''''''*'''";

Web API configuration after migration

yourEcoSpace.PersistenceMapper = persistenceMapperWEBAPIClient;
persistenceMapperWEBAPIClient.Uri = "https://YourServerMDrivenServer/api/A0_WebApi";
persistenceMapperWEBAPIClient.ServerUserName = "SomeMDrivenServerUser";
persistenceMapperWEBAPIClient.ServerPassword = "'''*''''''*'''";

The endpoint name is part of the URL. In this example, the controller endpoint is A0_WebApi, so the client URI ends in /api/A0_WebApi.

Complete client example

The following example configures a project persistence mapper in its constructor. It uses a local Web API endpoint; replace the URI and credentials for your environment.

public MDrivenProject9PMP() : base()
{
  this.InitializeComponent();

  MDriven.WebApi.Client.PersistenceMapperWEBAPIClient pm =
    new MDriven.WebApi.Client.PersistenceMapperWEBAPIClient();

  pm.Uri = "http://localhost:5003/api/A0_WebApi";
  pm.ServerUserName = "a";
  pm.ServerPassword = "123456";

  this.PersistenceMapper = pm;
}

Do not keep the WCF endpoint URL when changing client type. A WCF URL ending in .svc and a Web API URL under /api/ identify different server endpoints.

Create the server endpoint

On the server, create a Web API controller that derives from MDrivenPersistenceController<T>. T is the persistence mapper type for the application.

1. In the IIS web application, or equivalent hosted web application, create a folder for the Web API controller if that fits your project structure. For example, use a folder named WebAPI.
2. Add a Web API controller to the web application.
3. Change the controller base class to MDrivenPersistenceController<YourPMP>.
4. Name the controller so that its exposed route matches the URI configured by clients. For the client URI https://YourServerMDrivenServer/api/A0_WebApi, use the A0_WebApi endpoint name.
5. Deploy the web application and configure clients with the deployed HTTPS URL.

public class A0_WebApiController : MDrivenPersistenceController<YourPMP>
{
}

Replace YourPMP with the persistence mapper type for your application. The controller inherits the persistence Web API behavior from MDrivenPersistenceController<T>; do not replace the base class with the standard ApiController when the endpoint is intended to serve MDriven persistence communication.

Verify the connection

After deploying the controller and updating the client:

1. Start the client application.
2. Perform an operation that loads data through the EcoSpace.
3. Make and save a small data change that the authenticated user is allowed to make.
4. Confirm that the client reaches the Web API URL and that data is saved through the remote persistence layer.

If the client cannot connect, check these values first:

Check	Expected value
Client mapper type	PersistenceMapperWEBAPIClient, not PersistenceMapperWCFClient
Client URI	The deployed Web API URI, for example https://YourServerMDrivenServer/api/A0_WebApi
Controller base class	MDrivenPersistenceController<YourPMP>
Credentials	Values assigned through ServerUserName and ServerPassword
Hosting	The IIS web application, or equivalent host, is deployed and reachable at the configured URL

For IIS-related hosting information, see Documentation:IIS. For the framework API reference, see Documentation:Api documentation.

Related communication features

Web API persistence communication can also participate in MDriven realtime behavior. Attributes marked for realtime can be invalidated shortly after a committed change when clients use Web API communication with MDrivenServer. See Documentation:SignalR and Realtime for the realtime flow and configuration context.

See also

• Documentation:PersistenceMapperWEBAPIClient
• Documentation:SignalR and Realtime
• Documentation:IIS
• Documentation:Api documentation