Service Configuration

CODE Framework does its best to apply smart default settings to services (both server-side and client-side) for the typical type of application build with CODE Framework (business applications). Nevertheless, it is often desirable and necessary to change settings for services. This topic provides an overview of settings applicable to services.

Note that nearly all service settings (which are applied through the standard CODE Framework Configuration System) can be made globally for all services, or individual on a per-service basis. For instance, it is possible to set the allowable message size for all services through the ServiceMessageSize setting, and it is possible to apply that setting for a single service (example: ICustomerService) by adding a ServiceMessageSize:ICustomerService setting.

It is also possible to add settings programmatically in various ways. The most common approach is to use static events fired by the ServiceGarden (server-side) and ServiceClient (client-side) classes. These events grant access to all the low level WCF objects, so any conceivable WCF setting or manipulation can be made. A very common use of this feature is to arbitrarily change the URL a service is hosted at.

Note: This topic was originally called “WCF Service Configuration” when all CODE Framework Services Features were based on WCF. This has not been true for a long time now, since CODE Framework has supported hosting environments such as WebApi and .NET Core. However, the link to this topic has retained the "WCF" moniker in its name for consistency and backwards compatibility.

Server-Side Settings

These settings can be applied in server-side projects (these settings are used by the ServiceGarden class, which in turn is used by all CODE Framework WCF hosting environments):

Setting Default Description
ServiceBaseUrl localhost Root URL services are hosted at.
The default only applies for development environments.
In a production environment, this should be set to something like “www.mydomain.com”.
ServiceBasePort 50000 Base port used for TCP/IP (net.tcp) services. Ignored for all other service types.
This setting defines the first utilized port number. The first TCP/IP service hosted will receive this port number. The next host is incremented by 1, and so forth.
Note that this setting can only be set globally and not for individual services (although when launching services, a parameter on the host method allows defining the port explicitly)
ServiceBasePath dev Services are usually not just hosted at the root of a domain. For instance, a service project created to deal with payments is probably not hosted at
www.mydomain.com, but at
www.mydomain.com/payments
. In that case, ServiceBasePath would be set to "payments".
ServiceMessageSize medium Size of messages the service can process. This has an impact on the maximum buffer size, maximum buffer pool size, maximum message size, maximum array length, and maximum string content length.
CODE Framework supports 3 settings:
Default: WCF defaults apply
Medium: 10MB
Large: 100MB
VeryLarge: 1GB (this setting is not recommended!)
Max: int.MaxValue, about 2GB (this setting is def. not recommended!)
ServiceBasicHTTPExtension basic To differentiate between the same services hosted different ways, a suffix is usually added for Basic HTTP services URL unless this setting is an empty string in which case no suffix is added.
ServiceWsHttpExtension ws To differentiate between the same services hosted different ways, a suffix is usually added for WS HTTP services URL unless this setting is an empty string in which case no suffix is added.
ServiceRestExtension rest To differentiate between the same services hosted different ways, a suffix is usually added for REST services URL unless this setting is an empty string in which case no suffix is added.
ServiceRestXmlFormatExtension xml To differentiate between the same services hosted different ways, a suffix is usually added for REST XML services URL unless this setting is an empty string in which case no suffix is added.
ServiceRestJsonFormatExtension json To differentiate between the same services hosted different ways, a suffix is usually added for REST JSON services URL unless this setting is an empty string in which case no suffix is added.
ServiceConcurrencyMode multiple Defines whether a single hosted service supports multiple simultaneous callers (see also: [WCF Self-Hosted Service Concurrency])
ServiceMaxConcurrentSessions 10 Defines how many concurrent sessions a single hosted service supports (if multiple simultaneous callers are allowed) (see also: [WCF Self-Hosted Service Concurrency])
ServiceMaxConcurrentCalls 10 Defines how many concurrent callers a single hosted service supports (if multiple simultaneous callers are allowed) (see also: [WCF Self-Hosted Service Concurrency])
ServiceSecurityMode None Defines the security mode for TCP/IP (NetTcp) services. Allowed settings are None, Message, Transport, and TransportWithMessageCredential.

Client-Side Settings

These settings can be applied in client-side projects (these settings are used by the ServiceClient class)

Defines the security mode for TCP/IP (NetTcp) services. Allowed settings are None, Message, Transport, and TransportWithMessageCredentials.

Setting Default Description
ServiceBaseUrl localhost Root URL services are hosted at.
The default only applies for development environments.
In a production environment, this should be set to something like "www.mydomain.com”
ServiceBasePath dev Services are usually not just hosted at the root of a domain. For instance, a service project created to deal with payments is probably not hosted at
www.mydomain.com, but at
www.mydomain.com/payments
. In that case, ServiceBasePath would be set to "payments”.
ServiceMessageSize medium Size of messages the service can process. This has an impact on the maximum buffer size, maximum buffer pool size, maximum message size, maximum array length, and maximum string content length.
CODE Framework supports 3 settings:
Default: WCF defaults apply
Medium: 10MB
Large: 100MB
VeryLarge: 1GB (this setting is not recommended!)
Max: int.MaxValue, about 2GB (this setting is def. not recommended!)
ServiceBasicHTTPExtension basic To differentiate between the same services hosted different ways, a suffix is usually added for Basic HTTP services URL unless this setting is an empty string in which case no suffix is added.
ServiceWsHttpExtension ws To differentiate between the same services hosted different ways, a suffix is usually added for WS HTTP services URL unless this setting is an empty string in which case no suffix is added.
ServiceProtocol nettcp Defines the protocol that is to be used to call the service. Possible values are BasicHTTP, WsHTTP, NetTCP, REST, and InProcess.
Note: For more information on calling REST Services (such as those hosted in WebAPI), see Calling REST Services through Service Client.
ServicePort n/a Defines the port to be used to call a service. This only applies to TCP/IP (net.tcp) services. Note that it makes no sense to set this setting globally. It needs to be made for each service (example: ServicePort:ICustomerService = 45000)
ServiceRestExtension rest To differentiate between the same services hosted different ways, a suffix is usually added for REST services URL unless this setting is an empty string in which case no suffix is added.
ServiceRestXmlFormatExtension xml To differentiate between the same services hosted different ways, a suffix is usually added for REST XML services URL unless this setting is an empty string in which case no suffix is added.
ServiceRestJsonFormatExtension json To differentiate between the same services hosted different ways, a suffix is usually added for REST JSON services URL unless this setting is an empty string in which case no suffix is added.
ServiceUrl   This setting is used to define explicit service URLs. This is very commonly used for REST service calls. For SOAP-based services (BasicHttp and WsHttp), it can also be used when services are to be called from an arbitrary URL (such as when
the service is hosted by IIS). Otherwise, it is more common to set individual service settings (like the base URL and extension and such). (Note: This setting is always set as ServiceUrl:IXxxService for each service…)
ServiceSecurityMode None Defines the security mode for TCP/IP (NetTcp) services. Allowed settings are None, Message, Transport, and TransportWithMessageCredential.
ServiceClient::LogCommunicationErrors false When set to true, causes the ServiceClient class to send information into the LoggingMediator infrastructure to log additional information for failed calls (currently only used by REST services)

.NET Core Configuration

In .NET Core, configuration is often done through appsettings.json files. The syntax in those is slightly different as all settings with a colon (:) in them are expressed as hierarchical settings like so:

{
  "ApplicationSettings": {
    "RestServiceUrl": {
      "ICustomerService": "http://localhost:5008/api/customers",
      "IUserService": "http://localhost:5008/api/users"
    }
  }
}

To use this sort of configuration (which is dependency-injected in ASP.NET Core), add the following code to the Startup.cs file's constructor:

public Startup(IConfiguration configuration)
{
    Configuration = configuration;

    var appSettings = ApplicationSettingsJsonHelper.GetDictionaryFromSection(configuration);
    ConfigurationSettings.Sources.Insert(1, new DictionarySettings(appSettings));
}