App.config in detail

DevForce applications are usually configured using an external configuration file - an app.config for desktop (and sometimes Silverlight) applications, and a web.config for ASP.NET applications and the EntityServer when hosted by IIS.

With so many .config files in your projects; differences between design-time configuration and run-time configuration; differences between client and server; and further differences between development, test and deployed configurations, it's easy to be confused.  Here we'll try to make some sense of these files - what they should contain, and when you should use them.

Overview

Your first question may be "When do I need to use a .config file?" For now, you should assume you'll need a .config file whenever you need to override DevForce's default assumptions.  "But what are the DevForce defaults?" you wonder.  We'll describe these defaults below in detail, but generally if you need to tell DevForce something about your application:  "Where is the database?  Is there a remote EntityServer?  Where?  Where is the log file?" then you will likely need to supply this information via a .config file.  You can also programmatically supply configuration information, and in some cases supply configuration information via probed interface implementations (e.g., the IDataSourceKeyResolver  for dynamic database connection information is the most common).

If you create your application using one of the DevForce-supplied Visual Studio project templates, we've included simple .config files where appropriate to get you started.  You'll see a web.config in the web projects of your n-tier solutions, and an app.config in the desktop projects of both 2-tier and n-tier solutions; these files will contain the necessary information to get your application running.  You'll notice that the Silverlight application does not by default contain an app.config since it's usually not required, but we'll discuss that further below.  

As you add projects to your solution - for example a class library to hold your Entity Data Model - you may find these projects also contain an app.config file.  In the case of the EDM, the app.config is used only at design time by the EDM designer.  The only configuration files used at run-time - the only ones DevForce uses - will be the .config for your application executable and the web.config.  

As you develop your application and move from development to test to production environments your configuration will usually need to change too.  For example, log file locations, database connection strings, the URL of the EntityServer services - all might differ in the different environments.  You'll need to be aware of these changing needs and how to set configuration appropriate to each environment.

Discovery

Let's jump in and begin with the issue of discovery.  DevForce does have some DevForce-specific features regarding .config discovery, and it's good to understand these features early to avoid confusion later on.  

Silverlight

Unlike standard Silverlight applications in which the app.config (or System.Configuration) is not supported, DevForce Silverlight applications do support use of an app.config file.  Only the ideablade.configuration section can be specified in the file, since standard Microsoft-supplied configuration is not supported.  (Note the ServiceReferences.ClientConfig file is also supported in DevForce Silverlight applications for customization of WCF communications.)

DevForce will find the file if placed in the application project, named "app.config", and given one of the following build actions:

• Embedded Resource – to embed the file in the assembly
• Content – to leave the file as a loose file in the XAP, accessible for modification without recompilation

In most Silverlight applications the default configuration assumed by DevForce is sufficient and you will not need to supply an app.config at all.  

The default configuration assumes that the EntityServer is located in the same location from which the XAP was downloaded.  For example, if the XAP for your application was downloaded from http://myhost/myapp/default.aspx, DevForce will default the service URL to http://myhost/myapp/EntityService.svc.  If your EntityServer is located at this address, then you won't need an app.config in your Silverlight application.  If your EntityServer is at a different location, then you will need to override the DevForce default; you can do this by including an app.config with the appropriate <objectServer> information.  Changing the default with an app.config is optional -- you can also do this programmatically, or via a ServiceReferences.ClientConfig file.

A sample Silverlight app.config is provided in the deployment snippets available with the downloaded code.

Desktop / ASP.NET

In non-Silverlight applications, DevForce follows a slightly different “probing” path to find the app.config than standard .NET applications.  Standard .NET applications use only the application’s config file – MyApp.exe.config, or web.config for a web application.   In DevForce, the search for configuration information is as follows, and continues until a valid configuration is found:

1. If the ConfigFileLocation property of the IdeaBladeConfig object has been set in the executing code, DevForce will search the indicated location for a file named or matching “*.exe.config” (or “web.config” if a web project).  If not found, other *.config files in the folder are searched for a valid ideablade.configuration section.
   IdeaBladeConfig.ConfigFileLocation = @"c:\myapp";
2. If the IdeaBladeConfig.ConfigFileAssembly property has been set, DevForce will look for an embedded resource named “app.config” in the specified assembly.
   IdeaBladeConfig.ConfigFileAssembly = Assembly.GetExecutingAssembly();
3. Next, the current executable/bin folder is searched for a file named or matching “*.exe.config” (or “web.config” if a web project).  If not found, other *.config files in the folder are searched for a valid ideablade.configuration section.
4. DevForce next searches for an embedded resource named “app.config” in the entry assembly. 
5. If a valid Ideablade.configuration section was not found in any of the above locations then DevForce will create a default IdeaBladeConfig instance.  In some applications this default instance may be sufficient, but check your debuglog.xml if you find that your configuration is not being used.

Caution:   If you rely on DevForce-specific discovery - using an embedded resource or a loose config file not identified by .NET as the config file for the AppDomain - non-IdeaBlade sections of the config file will not be found by .NET.  

Note that in a test project, such as one created with MSTest, if you have enabled deployment you should also ensure that a loose config file is deployed, or set either the  IdeaBlade.ConfigFileLocation or IdeaBlade.ConfigFileAssembly properties, since standard DevForce probing may not work as expected.

Configuration contents and defaults

Now that we know how to find a .config file, what should we put in it?  DevForce defines the ideablade.configuration section to hold all IdeaBlade-specific configuration information.  At run-time, this information is used to load the single in-memory instance of the  IdeabladeConfig  class, available via the IdeaBladeConfig.Instance static property.

The ideablade.configuration section includes the following child elements.

Root element

In order to include the ideablade.configuration section in your config file you must "register" the section. You do this by placing a section element in the configSections, like so:

The configSections should be at the top of the configuration, so that the section registrations take place before the actual section.

The ideablade.configuration section looks like the following.  It can go anywhere in the config file after the configSections definitions.  Providing the namespace ensures that you can use Intellisense while editing the config in Visual Studio.  

ObjectServer Element

Settings controlling data service features, security, and communications to the EntityServer. 

The remoteBaseURL, serverPort and serviceName attributes are used to determine the "endpoint" address of the server when running in an n-tier configuration.  These settings are common to both client and server.  When running in IIS, or if using a system.serviceModel section to configure WCF services, you do not need to provide these fields.  A full URL, when built from these fields, might look something like "http://localhost:9009/EntityService" or "http://localhost/MyApp/EntityService.svc".  (Of course "localhost" is used only during development when both client and server are on the same machine.)

ClientSettings element

The clientSettings apply only to the client.  Child element of the objectServer element.  

ServiceKeys element

The serviceKeys apply to the client, but may be used on the server in some situations as defined below.  A serviceKey provides the address information for a single application server; a client application may communicate with multiple application servers.  Child element of the objectServer element.

ServiceKey attributes

The remoteBaseURL, serverPort and serviceName attributes are used to determine the "endpoint" address of a server when running in an n-tier configuration.  These attributes serve the same purpose on the serviceKey as they do when defined on the <objectServer> element itself.  You use one or more <serviceKey> definitions when your client application may communicate with multiple application servers.

The <serviceKeys> are not usually defined on the server, since their intention is to provide for multiple named servers, but they can be used there.  If the EntityServer is deployed as either a console application or Windows service then DevForce must determine the "base address" of the EntityServer.  It will use the attributes on the <objectServer> if present, otherwise it will look for a key named "default", and if not present use the first serviceKey defined.  

ServerSettings element

These settings concern server configuration.  In a 2-tier application without an application server tier you would include any serverSettings needed in the application config file.  The descriptions below indicate if a setting is specific to n-tier.  Child element of the objectServer element.

Logging Element

Controls the logging of run-time debug and trace information applicable to any configuration.

ProbeAssemblyNames Element

By default DevForce uses MEF (the Managed Extensibility Framework) to discover exported implementations of custom features.  In Silverlight applications, discovery uses the assemblies in the main XAP.  In all other applications, discovery uses the files in the exe/bin folder.  If the default discovery is insufficient you can specify additional assembly names here to be included when "probing".  

If you do find you need or want to specify the probe assembly names here, there are some naming rules to be aware of:

In Desktop and ASP.NET applications, you can use the assembly simple name; i.e., the assembly file name less the “.DLL” or “.EXE” extension. For example, for the DomainModel.dll assembly, use “DomainModel”.

In Silverlight applications, the assembly display name should be used. The display name includes the assembly simple name (defined just above), version, culture and public key token. For example, the assembly display name for the DomainModel.dll assembly might look like the following:

The public key will be non-null if you have signed the assembly.  The version number is the assembly version defined in your code.

EdmKeys Element

An EdmKey is used to uniquely identify a datasource in DevForce.  By default DevForce will build in-memory EdmKeys based on information in the <connectionStrings> element in the server's config file.  You can specify one or more EdmKeys here to override this behavior.  If the same key name is defined in both the EdmKeys and connectionStrings, the EdmKey specification will be used.

EdmKey attributes

Verifiers Element

Verifiers defined in the .config file are discovered by calling VerifierEngine.DiscoverVerifiersFromConfig . 

Verifier attributes

VerifierArg attributes

The verifier arguments are specific to the type of verifier.

NotificationService Element

Used to configure the notification or "push" service.

Configuration Editor

So how to edit your app.config or web.config?  You can edit directly in Visual Studio, and Intellisense will help guide you in the elements and attributes available, but if you'd like a more structured editor we've also provided the DevForce Configuration Editor to help in editing the ideablade.configuration section.  The editor provides descriptive help, and can eliminate many simple errors such as misspellings.  You can use the editor to modify an existing config file or create a new one.

You can use the Configuration Editor in two different ways:

1. Launch it from the DevForce 2010 folder in the Windows Start menu.
2. Configure it to work within Visual Studio. To do this:
   1. Select the app.config file, right-click, and select Open With… option.
   2. If you do not see ConfigEditor.exe in the list of programs, click the <Add…> button.
   3. On the Add Program dialog, click the ellipsis button to browse to a file. Navigate to the DevForce installation directory (typically C:\Program Files\DevForce 2010) and select the file ConfigEditor.exe from the Tools subfolder. Give it any “Friendly Name” you wish; e.g., “DevForce Configuration Editor”.
   4. Once DevForce Configuration Editor is in the list, double-click it to open the configuration file in that editor.