Jonathan Randall, Business Portal Developer Support
Microsoft Business Solutions
April 2005
Applies to
Business Portal 2.5
Business Portal SDK
Microsoft Business Framework
Microsoft Business Solutions
Summary: This article describes the configuration entity settings of the BusinessFramework.config file in the Business Portal, and how you can use them to change the behavior of the Business Portal application. (16 printed pages)
Contents
Introduction
Business Portal Configuration Settings
Conclusion
Introduction
This article describes the configuration entity settings that are contained within the Business Portal's BusinessFramework.config file. The Microsoft Business Framework (MBF) is a set of application development tools and object-oriented entities that are designed to make business application development easier and faster. MBF entities can be thought of as the "nouns" of an application. Entities always contain data, and may have processing capabilities that can act on that data.
Developers can use MBF to build many types of applications. The Business Portal SDK is a software development kit that is based on MBF. This article shows you how to use some of the MBF configuration entities that ship with the Business Portal SDK.
This article assumes that the reader is familiar with the Business Portal SDK and Microsoft Visual C#.
Configuration Entity Overview
Configuration entities are entities in MBF. The ConfigurationEntity class in MBF allows local machine configuration settings to be stored in the configuration file (BusinessFramework.config) alongside the Business Portal application. There are many configuration entities throughout the Business Portal application. These entities work in concert to configure the Business Portal application. The entities can affect data retrieval, troubleshooting operations, and visual styles within the Business Portal application. Within the BusinessFramework.config file, each configuration entity is represented as an XML node.
Business Portal Configuration Settings
The Business Portal configurations section of this article describes each Business Portal configuration entity and its attributes that can be modified by a Business Portal administrator.
Microsoft.BusinessFramework.BootSettings
The Microsoft.BusinessFramework.BootSettings node in the BusinessFramework.config file defines the values that control how an MBF application, such as Business Portal, is started.
The following table shows the properties of the BootSettings configuration entity that can be changed.
Table 1
| Property | Definition | Data Type | Default Value |
| isRemotingSupported | Indicates whether the application supports .NET Remoting. | Boolean | False. |
| enterpriseUrl | Stores the URL of the enterprise. | String | URL is defined during the Business Portal installation. |
| enterpriseName | Stores the name of the enterprise. | String | "Enterprise." |
Microsoft.BusinessFramework.CachePolicyConfig
The Microsoft.BusinessFramework.CachePolicyConfig node in the BusinessFramework.config file defines the values that control the caching of MBF entities and other configuration information within the Business Portal application.
The following table shows the properties of the CachePolicyConfig configuration entity that can be changed.
Table 2
| Property | Definition | Data Type | Default Value |
| isReadOnlySingletonCacheEnabled | Determines if read-only entity caching is enabled; master switch. | Boolean | True. |
| cacheTimeout | Contains a TimeSpan value that defines the amount of time before the user cache expires. | String | Twenty minutes. Format for this entry in the .config file is "hh:mm:ss." For example, "00:20:00" is twenty minutes. |
Microsoft.BusinessFramework.Data.Query.WebService.Settings
The Microsoft.BusinessFramework.Data.Query.WebService.Settings node in the BusinessFramework.config file controls the configuration of the Query Web Service (QWS) within the Business Portal application. Changing the settings in this node affects the behavior of the Web service.
The following table shows the properties of the QWS Settings configuration entity that can be changed.
Table 3
| Property | Definition | Data Type | Default Value |
| defaultExecuteBlockSize | Specifies the default block size that QWS uses while executing queries. | Integer | 100 |
| defaultExecuteInclusive | Indicates whether the last value in the current block should be the first value in the next block of results. | Boolean | False |
| enableVerboseExceptionReporting | Indicates whether to include verbose information in error reporting to clients. Verbose information includes members such as the stack trace. | Boolean | False |
| includeSystemEntities | Defines whether lists of views should include system MBF entities. | Boolean | False |
| schemaLocation | Provides the path location to the QWS schema file. | String | Created as part of the Business Portal installation process. |
| logDiagnostics | Indicates whether to log all diagnostics information with the MBF diagnostic subsystem. This setting should be enabled only in troubleshooting situations because excessive logging could degrade performance. | Boolean | False |
| validateOutput | Gets or sets a value that indicates whether to perform validation on the output XML. | Boolean | False |
Microsoft.BusinessFramework.Hypermedia.
HypermediaConfig
The Microsoft.BusinessFramework.Hypermedia.HypermediaConfig settings contained within this node in the BusinessFramework.config file control how the MBF Hypermedia subsystem reads the values from the BusinessFramework.config file.
The following table shows the properties of the HypermediaConfig configuration entity that can be changed.
Table 4
| Property | Definition | Data Type | Default Value |
| enableVerboseExceptionReporting | Indicates whether to include verbose information in error reporting to clients, which includes members such as the stack trace. | Boolean | False. |
| hypermediaSchemaPath | Provides the location to the Hypermedia schema file. | String | Defined during the Business Portal installation process. |
| validate | Gets or sets a value that indicates whether to perform validation when deserializing from XML. | Boolean | False. |
Microsoft.BusinessFramework.Hypermedia.Service.ServiceConfig
The Microsoft.BusinessFramework.Hypermedia.Service.ServiceConfig node in the BusinessFramework.config file is used to define how the Hypermedia service reads from the BusinessFramework.config file.
The following table shows the properties of the ServiceConfig configuration entity that can be changed.
Table 5
| Property | Definition | Data Type | Default Value |
| enableLogging | Specifies whether to log Hypermedia service exceptions with the MBF diagnostics subsystem. | Boolean | False. |
| providerRegistrationPath | Provides the path to the Provider Registration XML file. | String | Defined as part of the Business Portal installation process. |
| requestTimeout | Gets or sets the timeout setting for a Hypermedia request (in milliseconds). | Integer | 5000 milliseconds. |
Microsoft.BusinessFramework.Security.DatabaseAuthenticationConfig
The Microsoft.BusinessFramework.Security.DatabaseAuthenicationConfig node in the BusinessFramework.config file allows you to store information about the database authentication provider type within Business Portal. The entity settings in this node require the name type of the provider as well as the name of the specified assembly that contains the name of provider. This information is used to load and construct a database authentication provider within the Business Portal to perform authentication responsibilities with an SQL database.
The following table shows the properties of the DatabaseAuthenicationConfig configuration entity that can be changed.
Table 6
| Property | Definition | Data Type | Default Value |
| authenticationProviderTypeName | Retrieves the authentication provider type to be used by the application. | String | Defined during the Business Portal installation process. |
| hasEncryption | Indicates if encryption is needed. | Boolean | False. |
Microsoft.BusinessFramework.Entity.EntityServicePolicyFactoryConfig
The Microsoft.BusinessFramework.Entity.EntityServicePolicyFactoryConfig node in the BusinessFramework.config file defines and provides access to the configuration information for the EntityServicePolicyFactory class. This MBF class provides a consistent interface for data retrieval and map location policies. The Business Portal uses these data and map location policies to determine which data store the entity resides in.
The following table shows the properties of the EntityServicePolicyFactoryConfig configuration entity that can be changed.
Table 7
| Property | Definition | Data Type | Default Value |
| entityMapLocationPolicy | Stores the entity map location policy name. Format of the setting must be "TypeName, AssemblyName." | String | Default map location policy type is Microsoft. BusinessFramework. Entity. DefaultEntityMapLocationPolicy. |
| entityDataLocationPolicy | Stores the entity data location policy name. The name must be entered in a "TypeName, AssemblyName" format. | String | Default data location policy type is Microsoft. Dynamics. DataLocationPolicy. |
Microsoft.BusinessFramework.Security.SecureApplicationDirectoryList
The Microsoft.BusinessFramework.Security.SecureApplicationDirectoryList node in the BusinessFramework.config file provides a list of directories that contain applications built with MBF. The information in this node is used in conjunction with the Microsoft.BusinessFramework.BootSettings configuration setting to determine whether the MBF startup process needs to be initialized for these applications that are contained in the listed directories.
The following table shows the property of the SecureDataApplicationDirectoryList configuration entity that can be changed.
Table 8
| Property | Definition | Data Type | Default Value |
| directoryList | Gets and sets the list of directories. | String | Set during the installation of the Business Portal. |
Note The value for this section contains a pipe (|) symbol delimited list of all applications that require MBF code. This enables Microsoft SharePoint sites to contain both MBF code and non-MBF code. For example, if a project named "MyProject" was located in a directory located under the BusinessPortal directory, the value added to this section would be value=/sites/BusinessPortal/|/BusinessPortal/|/"MyProject"/.
Microsoft.Dynamics.DataLocationPolicyConfig
The Microsoft.Dynamics.DataLocationPolicyConfig node in the BusinessFramework.config file defines and provides access to the configuration information that is used by the MBF DataLocationPolicy class. The DataLocationPolicy class provides a means to determine, for each entity, the location information (the server and database name) that specifies the data store in which an entity resides. This information is defined within the DataLocationPolicy class.
The following table shows the properties of the DataLocationPolicyConfig configuration entity that can be changed.
Table 9
| Property | Definition | Data Type | Default Value |
| databaseServer | Accesses or sets the database server name. | String | Set during Business Portal installation. |
| databaseName | Indicates the name of the Microsoft SQL Server database that stores the MBF specific entities. Can also be referred to as the Enterprise database for the application. | String | Set during Business Portal installation. |
Microsoft.BusinessFramework.Portal.PortalConfig
The Microsoft.BusinessFramework.Portal.PortalConfig node of the BusinessFramework.config file contains the configuration details to access the Microsoft Windows SharePoint Services (WSS) object model. This information allows Business Portal to interact with WSS.
The following table shows the properties of the PortalConfig configuration entity that can be changed.
Table 10
| Property | Definition | Data Type | Default Value |
| wssObjectModelSiteURL | Defines the Secure Sockets Layer (SSL) URL for the WSS website. This is used to access the SharePoint object model. For non-SSL installations, this value is the same as the WSSSiteURL value. | String | Defined during the installation of Business Portal. Typically, it is the URL to a website that has been extended by WSS. |
| wssSiteURL | Defines the URL to the WSS website used for access the SharePoint object model. This setting is valid only if SSL is disabled. | String | Defined during the installation of the Business Portal. Typically, it is the URL to a website that has been extended by WSS. |
| cacheMenuExpirationMinutes | Determines the length of time (in milliseconds) that the menus for Web parts are cached. | Int32 | 4320 milliseconds. |
Microsoft.BusinessFramework.Portal.DataCenter.Config
The Microsoft.BusinessFramework.Portal.DataCenter.Config node in the BusinessFramework.config file details the settings that control the visual styles and behavior of the data centers within the Business Portal.
The following table shows the properties of the DataCenter configuration entity that can be changed.
Table 11
| Property | Definition | Data Type | Default Value |
| defaultConfigXmlPath | Specifies the path to the default .config XML file. | String | DefaultConfig.xml |
| folderExplorerStyle | Sets the style that the folder explorer uses. This setting provides a list of arguments that specify the window size and GUI decorations. | String | dialogHeight:425px;
dialogWidth:505px;help:no; status:no;resizable:no; |
| folderExplorerUrl | Defines the URL to the default folder explorer. | String | /UI/ClientCommon/
FolderOrganizer/ default.aspx This value is relative to the Business Portal's installed location. |
| formViewDefaultTransform | Stores the name of the default form view transform file. | String | DefaultForm.xslt |
| formViewDirectory | Gets or sets the directory where form view transforms are found. | String | /BusinessPortal
/Portal /DataCenter /Forms This value is relative to the Business Portal's installed location. |
| officeDownloadUrl | Provides the URL to the Microsoft Office download site. | String | http://office.microsoft.com/downloads/default.aspx |
| optionsDialogStyle | Provides a list of arguments that define the visual style for the Options dialog box with the Business Portal Data Center window. | String | dialogHeight: 285px; dialogWidth: 475px; help: no; status: no; resizable: no; |
| optionsDialogUrl | Provides the name of the Options dialog box file name. | String | OptionsDialog.aspx |
| optOutDialogStyle | Provides a list of arguments that determine the visual style of the Options dialog box windows. | String | dialogHeight: 185px; dialogWidth: 500px; edge: Sunken; center: Yes; help: No; resizable: No; status: No; |
| optOutDialogUrl | Provides the URL to the options dialog. aspx file. | String | /UI
/ClientCommon /Dialog /YesNoOpt.aspx This is relative to the Business Portal's installed location. |
| queryBuilderTabbedStyle | Provides a list of arguments that determines the visual style for the Query Builder windows. | String | dialogHeight:565px;
dialogWidth:535px;help:no; status:no;center:no; |
| queryBuilderTabbedUrl | Specifies the URL to the tabbed Query Builder's .aspx file. | String | /UI
/QueryBuilder /qbTabbed.aspx This is relative to the Business Portal's installed location. |
| queryBuilderWizardStyle | Provides a list of arguments that define the visual style for the Query Builder Wizard windows. | String | dialogHeight:500px;
dialogWidth:700px; help:no; status: no |
| queryBuilderWizardUrl | Provides access to the URL of the Query Builder Wizard window. | String | /UI
/QueryBuilder /qbWizard.aspx This is relative to the Business Portal's installed location. |
| qwsLocation | Provides the URL of the QWS. | String | /BusinessPortal
/QueryWebService.asmx This is relative to the Business Portal's installed location. |
| sourceFilePath | Provides the path to the data center source file. | String | DataCenterSource.xml |
| toolbarLocation | Provides the path to the toolbar .htc file. | String | Toolbar.htc |
| userPreferencesWebServiceLocation | Provides the URL of the User Preferences Web Service. | String | /BusinessPortal
/UserPreferencesWebService.asmx This is relative to the Business Portal's installed location. |
Microsoft.Dynamics.DynamicsUnitProviderConfig
The Microsoft.Dynamics.DynamicsUnitProviderConfig node in the BusinessFramework.config file defines and provides access to the configuration information that is used by the DynamicsUnitProvider class within the Business Portal. The main purpose of the DynamicsUnitProvider class is to produce a representation of a Quantity value in its base unit of measure.
The following table shows the properties of the DynamicsUnitProviderConfig configuration entity that can be changed.
Table 12
| Property | Definition | Data Type | Default Value |
| expirationType | Provides an enumeration that defines how long the DynamicsUnitProvider object is cached by the Business Portal application. | Enum | TimeoutExpire |
| hours | Combines with minutes and seconds to assist in defining a time span in which the DynamicsUnitProvider object remains cached by the Business Portal application. | Integer | 3 |
| minutes | Combines with hours and seconds to assist in defining a time span in which the DynamicsUnitProvider object remains cached by the Business Portal application. | Integer | 0 |
| seconds | Combines with hours and minutes to assist in defining a time span in which the DynamicsUnitProvider object remains cached by the Business Portal application. | Integer | 0 |
Microsoft.BusinessFramework.Diagnostics.DiagnosticConfiguration
The Microsoft.BusinessFramework.Diagnostics.DiagnosticConfiguration node in the BusinessFramework.config file controls the diagnostic instrumentation of the Business Portal application. The Business Portal administrator can control where tracing and logging information is stored or what to do when an assertion fails. In addition, the Business Portal administrator can decide how much detail is provided in the traces and logs.
The following table shows the properties of the DiagnosticConfiguration configuration entity that can be changed.
Note These settings should be changed only for troubleshooting purposes. Leaving these settings active in production environments could severely impact the performance of the Business Portal application.
Table 13
| Property | Definition | Data Type | Default Value |
| assert | Writes a log record with a severity of Error when an assertion occurs. Additionally, a trace record is written by using a trace level of Error. Setting the value to Abort halts execution and throws a PlatformFailException exception. A Throw setting throws PlatformAssertException but execution continues. Setting the value to Ignore logs the assertion and continues the execution of the application. | Enum (Ignore, Throw,
Abort) | Abort |
| verify | Writes a log record with a severity of Error when an assertion occurs. However, setting the Enumeration value to Throw results in PlatformVerifyException. | Enum (Throw, Abort) | Abort |
| log | Affects the severity at which log records are recorded. There are four possible values: Info, Warning, Error, and None. Info provides the most verbose recordings. Warning records log messages for both Warning severities and Error severities. Error logs only messages with an Error severity. Setting the property to None provides for no log messages. | Enum (Info, Warning, Error, None) | Info |
| trace | Defines the severity at which trace messages are recorded. There are four possible values: Info, Warning, Error, and None. Info provides the most verbose recordings. Warning records messages for both Warning and Error severities. Error records only messages with an Error severity. None provides for no trace messages. | Enum (Info, Error, Warning, None) | Info |
| listener | To log diagnostic messages, listeners must be defined and configured. Business Portal can have up to 10 listeners. To define a listener element, start with listener and then append a number up to ten (for example, listener1). The value of the element is set to a type of Diagnostics listener that exists in MBF. | String | Microsoft. BusinessFramework. Diagnostics. DiagnosticsLogEventListener |
Microsoft.BusinessFramework.Diagnostics.
DiagnosticsLogEventListener-Configuration
The Microsoft.BusinessFramework.Diagnostics.DiagnosticsLogEventListener-Configuration node in the BusinessFramework.config file is associated with the Microsoft.BusinessFramework.Diagnostics.DiagnosticConfiguration setting. While the DiagnosticConfiguration setting allows an administrator to define the severity in which messages are recorded and listeners are added to the application, these settings give the administrator granular control over the behavior of each type of listener. The administrator can then decide which machine to record the messages to, along with the source name of the message and the log in which to store the message. Both the DiagnosticsLogEventListener node and the DiagnosticsTraceEventListener class record messages to the Microsoft Windows Server event log.
The following table shows the properties of the DiagnosticsLogEventListener-Configuration configuration entity that can be changed.
Table 14
| Property | Definition | Data Type | Default Value |
| machineName | Controls the name of the target machine in which log and/or trace messages are written to. | String | "." |
| sourceName | Default event source name that is used for initialization. | String | MicrosoftBusinessFrameworkLog |
| logName | Specifies the name of the Windows Server event log that the messages are written to. | String | Application |
Microsoft.BusinessFramework.Diagnostics.
DiagnosticsTraceEventListener-Configuration
The Microsoft.BusinessFramework.Diagnostics.DiagnosticsTraceEventListener-Configuration node in the BusinessFramework.config file configures the DiagnosticsTraceEventListener class to record trace messages to the Windows Server event log. The configuration is the same as the DiagnosticsLogEventListener node. The only difference in the listener types is that one is used with log messages and the other specifies the destination for trace messages.
The following table shows the properties of the DiagnosticsTraceEventListener-Configuration configuration entity that can be changed.
Table 15
| Property | Definition | Data Type | Default Value |
| machineName | Controls the name of the target machine that log and/or trace messages are written to. | String | "." |
| sourceName | Provides the default event source name that is used for initialization. | String | MicrosoftBusinessFrameworkTrace |
| logName | Specifies the name of the Windows Server event log that the messages are written to. | String | Application |
Microsoft.BusinessFramework.Diagnostics.
TraceTextListener-Configuration
The Microsoft.BusinessFramework.Diagnostics.TraceTextListener-Configuration node in the BusinessFramework.config file defines the configuration for another type of listener in MBF—the TraceTextListener. This listener writes messages to a file on the local file system rather than to the Windows Server event log.
The following table shows the property of the TraceTextListener-Configuration configuration entity that can be changed.
Table 16
| Property | Definition | Data Type | Default Value |
| fileName | Stores the name of the file that the output stream is being written to. | String | TraceTextListener.log |
Microsoft.BusinessFramework.Diagnostics.
LogMessage-Configuration
The Microsoft.BusinessFramework.Diagnostics.LogMessage-Configuration node in the BusinessFramework.config file controls the amount of information that is contained within the log messages that the diagnostic instrumentation records. A message can have information, such as the UserName, ProcessId, ThreadId, OffSet, CurrentTime, ClassName and MethodName, included as the message is logged.
The following table shows the properties of the DiagnosticsTraceEventListener-Configuration configuration entity that can be changed.
Table 17
| Property | Definition | Data Type | Default Value |
| displayUserName | Indicates whether the thread's user context is included in the log message. | Boolean | False |
| displayProcessId | Indicates whether to include the unique identifier of the current process in the log message. | Boolean | False |
| displayThreadId | Indicates whether to include the unique identifier of the associated thread in the log message. | Boolean | False |
| displayOffset | Indicates whether to include the offset of the method associated with the current process in the message. | Boolean | False |
| displayCurrentTime | Indicates whether to include the time at which the current diagnostic message was generated. | Boolean | False |
| displayMethodName | Indicates whether to include the name of the method that is associated with the current process. | Boolean | False |
| displayClassName | Defines whether the name of the class associated with the current process can be displayed. | Boolean | False |
Microsoft.BusinessFramework.Diagnostics.
TraceMessage-Configuration
The Microsoft.BusinessFramework.Diagnostics.TraceMessage-Configuration node in the BusinessFramework.config file controls the amount of information that is contained within the trace messages that the diagnostic instrumentation records. A message can have information, such as the UserName, ProcessId, ThreadId, OffSet, CurrentTime, ClassName and MethodName, included as the trace message is recorded.
The following table shows the properties of the TraceMessage-Configuration configuration entity that can be changed.
Table 18
| Property | Definition | Data Type | Default Value |
| displayUserName | Indicates whether to include the thread's user context within the trace message. | Boolean | False |
| displayProcessId | Indicates whether to include the unique identifier of the current process within the trace message. | Boolean | False |
| displayThreadId | Indicates whether to include the unique identifier of the associated thread within the trace message. | Boolean | False |
| displayOffset | Indicates whether to include the offset of the method that is associated with the current process within the message. | Boolean | False |
| displayCurrentTime | Indicates whether to include the time at which the current diagnostic message was generated. | Boolean | False |
| displayMethodName | Indicates whether to include the name of the method that is associated with the current process. | Boolean | False |
| displayClassName | Defines whether the name of the class that is associated with the current process can be displayed. | Boolean | False |
Conclusion
This article has reviewed the configuration entities that are in the Business Portal application. The configuration entities that exist in the Business Portal application can have their behavior controlled through the BusinessFramework.config file. The configuration entities can be used in a variety of ways. The Business Portal application can be modified through these entities to help you troubleshoot, improve performance, or change visual styles.
Support for the Business Portal SDK is available for registered customers and partners by visiting https://mbs.microsoft.com/support/newstart.aspx or by calling (888) 477-7877.