This is documentation for the current major version Apprenda 7.
Documentation for older versions are also available.

WCF Web Services

This pages explains how to create WCF web services that will run on the Platform. Before creating your own, you should understand how the Platform will deploy and mange WCF services.

WCF Web Services on Platform

While not required for your guest application, it is recommended that business logic of .NET guest applications be placed inside of WCF web services. Architecturally speaking, this is the best way to achieve logical separation of application tiers. The Platform also provides the following benefits to your WCF web services:

  • Linear scale-out and load distribution across all servers on the grid through P2P (i.e., decentralized) SOAP routing capabilities
  • Built-in fault detection and automated service revival 
  • Automatic re-deployment of the service elsewhere on the grid if necessary (i.e. another server hosting the service goes offline)
  • Managed deployment and control of service instances via the Developer Portal and System Operations Center (SOC)
  • Support for Visual Studio remote debugging
  • Support for Apprenda Extensions (including modifiable request/response pipelines, custom configuration, etc.)
  • Automated teardown of unused services

Applications may have multiple WCF web services, each of which are deployed independently, allowing each to have different scaleout mechanics and recovery options summarized above.

WCF services on the Platform should be stateless. This is because they are always shared between multiple Tenants, and service requests are randomly distributed across all available instances of the WCF service. The Platform will also deploy and tear down instances of the service at any time. 

Constructing WCF Client Proxies for on Platform Application Components

Because the Platform is responsible for deploying your WCF web service to one or more servers running your Platform, it is necessary to use configuration to specify the address of your service as opposed to explicitly referencing an address or endpoint in code, as demonstrated by the following example: 

C# Example

//Valid
IMyService proxy1 = new MyServiceProxy();

//Invalid #1
IMyService proxy2 = new MyServiceProxy("namedEndpoint");

//Invalid #2
IMyService proxy3 = new MyServiceProxy(new NetTcpBinding(), new EndpointAddress("net.tcp://server:9000/m"));

All client configuration is detected automatically, and changed at deployment time to point to an address that is resolvable by the Platform's router at a later time, based on the deployment characteristics of your application at runtime.

Note: This information applies to the configuration of clients that are deployed using the Platform, such as an ASP.NET application or a WCF service that initiates a connection to another WCF service. Contacting Platform services from outside of the grid topology (e.g. via the Remote API) requires alternate configuration.

Architectural Restrictions for WCF Web Services

When developing your WCF services, bear in mind the following restrictions:

  1. The Platform supports WCF services that are InstanceContextMode of PerCall or Single; PerSession mode is not supported at this time.
  2. Service classes cannot be marked as sealed.  Any sealed WCF service classes will be rejected on upload. 
  3. Platform version 7.1.0 introduces support for some custom behaviors. In Platform versions before 7.1.0, custom bindings or behaviors are not allowed at either the service or client level. Any custom bindings or behaviors configured are ignored and will not be installed.
  4. ServiceHost extensions via the WCF IExtension<T> interface cannot be installed. The Platform will reject any attempts to install extensions at runtime, which will prevent code from being deployed.
  5. WCF callback functionality is not currently supported. Any callback functionality will be ignored at runtime.

WCF Service Behaviors

As of Platform version 7.1.0, the Platform allows you to define a limited set of service behaviors for your WCF web services. When developing a WCF service, the Platform will preserve the configuration for the supported custom behaviors before applying Platform-specific configuration changes to your service and deploying it to the Platform. In Platform versions before 7.1.0, clients must exclude custom behaviors as these declarations will be lost when the Platform configures your client.

When multiple service behaviors are defined for a WCF service, the Platform will select and preserve only the first service behavior in the configuration. A Platform WCF component can only have a single service associated with the component and the service behavior preserved will be the one applied to that service. Configuration from the remaining behaviors will be removed before applying the final configuration changes for hosting the service on the platform.

Supported Service Behavior Element Extension Sections

  • serviceDebug
  • serviceMetadata
  • dataContractSerializer
  • serviceThrottling

Unsupported Service Behavior Element Extension Sections

The following are not supported and will be excluded from the WCF configuration file.
  • serviceCredentials

Additionally, the service behavior name "NestingServiceBehavior" is reserved for use by the Platform. If found in the configuration file, the Platform will remove it before applying the final configuration changes for hosting on the Platform. To use the settings from this service behavior on the Platform it must be renamed and placed as the first service behavior in the configuration file.

Configuring WCF Services to Run Locally

The Platform uses custom behaviors to "flow" contextual information to services automatically when they are called. When the Platform deploys your clients and services to the grid, the custom behaviors are installed automatically. To simulate this flow when running services locally on the developer workstation in Visual Studio, you'll need to set up this behavior yourself. 

If you create your service using the Visual Studio template included with the Apprenda SDK, the appropriate configuration will be done automatically.

The Apprenda behavior extension Apprenda.Apprenda.API.Local.ContextEndpointBehaviorExtension (found in Apprenda.API.Local.dll) needs to be applied on all net.tcp and http endpoints, as demonstrated in the following example of a service's configuration:

App.config SaaSGrid Additions

<extensions>
  <behaviorExtensions>
    <add name="ContextBehavior" 
         type="Apprenda.SaaSGrid.API.Local.ContextEndpointBehaviorExtension, 
                    . . . SaaSGrid.API.Local, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  </behaviorExtensions>
</extensions>

<behaviors>
  <endpointBehaviors>
    <behavior name="ApprendaEndpointBehavior">
      <ContextBehavior />
    </behavior>
  </endpointBehaviors>
</behavior>

<services>
   <service name="Service.Service">

      <!-- Sample TCP configuration -->
      <endpoint address="net.tcp://localhost:40000/Service" binding="netTcpBinding"
              bindingConfiguration="DefaultTcpBinding"
              behaviorConfiguration="ApprendaEndpointBehavior"
              contract="Service.IService" />
 
      <!-- Sample HTTP configuration -->
      <endpoint address="http://localhost:40001/Service" binding="basicHttpBinding"
              bindingConfiguration="DefaultBasicHttpBinding"
              behaviorConfiguration="ApprendaEndpointBehavior"
              contract="Service.IService"/>
      . . . 
   </service>
</services>

Threading and Application Domains

The Platform provides added infrastructure to support threading models (e.g. ThreadPool usage, asynchronous method invocation) and use of AppDomains in Apprenda-hosted code. The Apprenda runtime maintains context and identity on asynchronous code invocations.  Context information from the forking thread is copied to the target thread at any asynchronous invocation point.  In addition, context information is propagated across AppDomain remoting boundaries.