Service Configuration Editor

Windows Communication Foundation (WCF) Service Configuration Editor enables administrators and developers to create and modify configuration settings for WCF services using a graphical user interface (GUI). With this tool, you can manage settings for WCF bindings, behaviors, services, and diagnostics without having to directly edit XML files.

For a guide to some common tasks using Service Configuration Editor, see Using Service Configuration Editor.

For additional resources, see Service Configuration Editor Resources.

Build Date: 2009-11-05


Using Service Configuration Editor

The Windows Communication Foundation (WCF) Service Configuration Editor (SvcConfigEditor.exe) allows administrators and developers to create and modify configuration settings for WCF services using a graphical user interface. With this tool, you can manage settings for WCF bindings, behaviors, services, and diagnostics without having to directly edit XML configuration files.

Using Service Configuration Editor

Service Configuration Editor comes with a wizard that guides you through all the steps in configuring a WCF service or client. You are strongly advised to use the wizard instead of the editor directly. You can use Service Configuration Editor to create a new WCF configuration settings file with the assistance of a wizard or to modify existing settings files.

If you already have some configuration files that comply with the standard System.Configuration schema, you can manage specific settings for bindings, behavior, services, and diagnostics with the user interface. The Service Configuration Editor enables you to manage the settings for existing WCF configuration files as well as executable files, COM+ services, and Web-hosted services. When open a Web-hosted service with Service Configuration Editor, both the service’s own configuration and inherited configurations sections of upper level nodes are shown. For more information, see Modify Existing Configuration Files.

You can also use Service Configuration Editor to create new configuration files with the aid of a wizard. For more information, see Create a New Configuration File.

Because WCF configuration settings are located in the <system.serviceModel> section of the configuration file, the editor operates exclusively on the content of this element and does not access other elements in the same file. You can navigate to existing configuration files directly, or you can select an assembly that contains a service, virtual directory, or COM+ service. The editor loads the configuration file for that particular service and allows the user to either add new elements or edit existing elements nested in the <system.serviceModel> section of the configuration file.

The editor supports IntelliSense and enforces schema compliance. The resulting output is guaranteed to comply with the schema of the configuration file and to have syntactically correct data values. However, the editor does not guarantee that the configuration file is semantically valid. In other words, the editor does not guarantee that the configuration file can work with the service it configures.

Caution:
The editor cannot purge a configuration element from the configuration file once you have modified the element. For example, if you use the editor to set the endpoint name to a non-empty string and save it, the configuration file has the following content: <endpoint binding="basicHttpBinding" name="somename" /> If you attempt to remove the name by setting it to an empty string and save the file, the configuration file still contains the name attribute: <endpoint binding="basicHttpBinding" name="" /> To purge the attribute, you must manually edit the element using another text editor. You should be especially careful with this issue when you use the issueToken element of the clientCredential Endpoint behavior. Specifically, the address attribute of its localIssuer sub-element must not be an empty string. If you have modified the address attribute using the Configuration Editor and want to remove it completely, you should do so using a tool other than the Editor. Otherwise, the attribute will contain an empty string, and your application will throw an exception.


Modify Existing Configuration Files

This section includes information about using Windows Communication Foundation (WCF) Service Configuration Editor to change settings in existing configuration files.

See Create a New Configuration File for information about using the New Service Element Wizard, which is the simplest way to generate a new configuration file.

In This Section

Open a Configuration File

Shows the steps to use to open a configuration file.

Create or Edit a Service Configuration

Shows how to create or edit a service configuration.

Create or Edit a Client Configuration

Shows how to create or edit a client configuration.

Edit Binding Configurations

Shows how to configure bindings on endpoints.

Edit Diagnostics Configurations

Shows how to turn performance counters on or off, enable or disable Windows Management Instrumentation (WMI), configure WCF tracing, and configure WCF message logging.

Edit Behaviors Configurations

Shows how to configure behaviors of endpoints and services.

Manage Extensions

Shows how to register behavior extensions.


Open a Configuration File

Service Configuration Editor (SvcConfigEditor) enables you to manage the settings for existing Windows Communication Foundation (WCF) configuration files as well as executable files, COM+ services, and Web-hosted services.

SvcConfigEditor accepts any configuration file that complies with the System.Configuration schema. You can navigate to existing configuration files directly, or you can select an assembly that contains a service, virtual directory, or COM+ service.

The viewer automatically follows the configuration merge path and creates a view of the merged configuration. For example, the actual configuration of a non-hosted service is a combination of Machine.config and App.config. Any changes are applied to the active file in the SvcConfigEditor. If you want to edit a specific file in the configuration merge path, you should open it directly.

The Service Configuration Editor user interface is divided into the following areas:

  • Tree View Pane, which displays configuration elements in a tree structure on the left. You can perform operations in the tree by right-clicking the nodes.

  • Task Pane, which displays common tasks for current elements on the lower-left of the window.

  • Detail Pane, which displays detailed settings of the configuration node selected in the Tree View on the right.

Opening a Configuration File

To open a configuration file

  1. Start the SvcConfigEditor by using a command window to navigate to C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin\ , and then type SvcConfigEditor.exe.

  2. From the File menu, select Open and click the type of file you want to manage. You can open configuration files directly, browse for WCF /COM+ services, and open configuration files for Web-hosted services.

  3. In the Open dialog box, navigate to the specific file you want to manage and double-click it.

Note:
The editor only operates on the System.ServiceModel section of the configuration file. It does not modify any other configuration sections present in the configuration file.

The viewer automatically follows the configuration merge path and creates a view of the merged configuration. For example, the actual configuration of a non-hosted service is a combination of Machine.config and App.config. Any changes are applied to the active file in the Service Configuration Editor. If you want to edit a specific file in the configuration merge path, you should open it directly.

In addition, Service Configuration Editor reloads the currently opened configuration file when the latter has been modified outside the Editor. When this happens, all the changes that are not durably saved inside the Editor will be lost. If reloading happens consistently, the most likely cause is a service that constantly accesses the configuration file, e.g., an antivirus software running in the background. To resolve this, ensure that Configuration Editor is the only process that can access the file when it is opened.


Create or Edit a Service Configuration

The Services node displays all of the services currently assigned in the configuration file. Each sub-node in the tree corresponds to a sub-element of the <services> element in the configuration file.

When you click the Services node, you can view or perform basic tasks on the service Summary Page in the Detail Pane.

Creating a new Service Configuration

You can create a new service configuration in the following ways.

  • Using a Wizard: Click the link Create a New Service… on the Task Pane or Summary Page to launch the wizard. You can also do so in the File menu -> Add New Item.

  • Create manually: You can right-click the Services node and choose New Service.

Creating a new Service Endpoint Configuration

You can create a new service endpoint configuration in the following ways.

  • Using a Wizard: Click the Create a New Service Endpoint… link on the Task Pane or Summary Page to launch the wizard. You can also do so in the File menu -> Add New Item.

  • Create manually: Once you created a Service, you can right-click the Endpoints node and choose New Service Endpoint.

Editing a Service Configuration

To edit a service configuration

  1. Click a Service node.

  2. Edit the settings in the property grids.

Editing a Service Endpoint Configuration

To edit a service endpoint configuration

  1. Click a Service Endpoint node.

  2. Edit the settings in the property grids.

Adding a Base Address

To add a base address

  1. Click the Host node.

  2. Click the New… button in the Base Addresses section.

  3. Enter the base address URI in the dialog box.

  4. Click OK.
Caution:
You cannot edit the value of <baseAddressPrefixFilters> inside this tool. To add or modify this element, you should use a text editor or Visual Studio.


Create or Edit a Client Configuration

The Client node displays all of the client endpoints in the configuration file. Every sub-node in the tree corresponds to a sub-element of the <client> element in the configuration file.

When you click the Client node, you can view or perform basic tasks on the client Summary Page in the Detail Pane.

Creating a new Client Endpoint Configuration

You can create a new client endpoint configuration in the following ways.

  • Create by Wizard: Click the Create a New Client… link on the Task Pane or Summary Page to launch the wizard. You can also do so in the File menu -> Add New Item.

  • Create manually: Right-click the Endpoints node under Client and choose New Client Endpoint.

Editing a Client Endpoint Configuration

To edit a client endpoint configuration

  1. Click a Client Endpoint node.

  2. Edit the settings in the property grids.


Create or Edit a Standard Endpoint Configuration

Standard endpoints are specialized endpoints that have one or more aspects of the address, contract and binding set to default values.

Such configuration settings are stored in the Standard Endpoint node. The Standard Endpoint node displays all of the standard endpoint settings in the configuration file. Every sub-node in the tree corresponds to a sub-element in the <standardEndpoints> element in the configuration file.

When you click the Standard Endpoint node, you can view or perform basic tasks on the standard endpoint Summary Page in the Detail Pane.

Creating a New Standard Endpoint Configuration

You can create a new standard endpoint configuration in the following ways.

  • Right-click the Standard Endpoint node and select New Standard Endpoint Configuration… Select the binding type in the dialog box and click OK.

  • Select the Standard Endpoint node and click New Standard Endpoint Configuration… in the Task Pane on the lower-left of the window.

The Creating a New Standard Endpoint dialog box displays and lists all registered standard endpoint types.

Viewing and Edit a Standard Endpoint Configuration

You can open a standard endpoint configuration for viewing and editing in the following ways.

  • Click to expand the Standard Endpoint node and click the respective endpoint subnode.

  • Click the Standard Endpoint node and click the respective endpoint on the Detail pane.

Attributes for the endpoint will be shown in the right pane for editing.

Deleting a Standard Endpoint Configuration

You can delete a standard endpoint configuration in the following ways.

  • Click to expand the Standard Endpoint node and right-click the respective endpoint subnode. Use the context command Delete Standard Endpoint Configuration to delete the endpoint.

  • Click the Standard Endpoint node. In the Task pane, click Delete Standard Endpoint Configuration.

If the standard endpoint is in used, a warning message will be displayed when you attempt to delete it. The warning is The standard endpoint is in use. If you delete it now, please be sure to delete all of its references in other parts of the configuration (for example, in the service endpoint or client endpoint). Otherwise, the configuration will be invalid and cannot be opened next time. Are you sure you want to delete the standard endpoint?”.


Edit Binding Configurations

Binding configurations are used to configure bindings on endpoints. Such configuration settings are stored in the Binding node. Endpoints reference binding configurations by name and multiple endpoints can reference a single binding configuration.

The Bindings node displays all of the binding settings in the configuration file. Every sub-node in the tree corresponds to a sub-element in the <bindings> element in the configuration file.

When you click the Bindings node, you can view or perform basic tasks on the binding Summary Page in the Detail Pane.

Creating a New Binding Configuration

You can create a new binding configuration in the following ways:

  • Right-click the Bindings node and select New Binding Configuration…. Select the binding type in the dialog box and click OK.

  • Select the Bindings node and click New Binding Configuration… in the Task Pane.

  • In the service or client summary page, click Click to Create in the Binding Configuration field to create a binding configuration for the corresponding endpoint.

Adding Binding Element Extensions to a Custom Binding

To add binding element extensions to a custom binding

  1. Select the binding you want to add an extension element to.

  2. Click Add.

  3. From the list of available extensions, select the binding element extension you want to add. You can select multiple items by pressing the CTRL key simultaneously.

  4. Click Add.

Adjusting the Extension Position in a Custom Binding

A custom binding is a collection of binding elements that form a stack. Each binding element on the stack has its own configuration settings. The order of the binding element extensions in a custom binding indicates their positions in the stack. Elements at the top of the stack are applied first.

To adjust the extension position in a custom binding

  1. Select the custom binding node.

  2. Select one binding extension element in the Binding Element Extension Position section.

  3. Use the “Up” or “Down” button on the left side of the list to change the position of the selected element.

Editing the Configuration of Binding Element Extensions in a Custom Binding

To edit the configuration of binding element extensions in a custom binding

  1. Select the binding node in the tree.

  2. Select the custom binding that contains the element you want to edit.

  3. Select the binding element extension you want to edit. The settings of the element appear in the right pane, where they can be edited.


Edit Diagnostics Configurations

The Diagnostics node displays all of the diagnostic settings in the configuration file. It enables you to turn performance counters on or off, enable or disable Windows Management Instrumentation (WMI), configure Windows Communication Foundation (WCF) tracing, and configure WCF message logging. The settings in the Diagnostics node correspond to the <system.diagnostics> section in the configuration file.

When you click the Diagnostics node, you can view or perform basic tasks on the diagnostics Summary Page in the Detail Pane.

Configuring performance counters and WMI

To configure performance counters and WMI

  1. Click the Diagnostics node.

  2. Click Toggle Performance Counters. The performance counter has three states: Off (default), ServiceOnly, and All. Clicking the link toggles the setting among these three states.

Configuring a WMI Provider

To configure a WMI provider

  1. Click the Diagnostics node.

  2. To enable a WMI provider, click the Enable WMI Provider link.

Enabling WCF Tracing

You can create a WCF trace file with standard properties or set up a custom trace file.

To enable WCF tracing

  1. Click the Diagnostics node.

  2. Click Enable Tracing.

  3. Click the Trace Level link to adjust the trace level. There are six trace levels: Off, Critical, Error, Warning, Information, and Verbose. The Activity Tracing and Propagate Activity option enable you to use the WCF activity tracing feature.

  4. Click the trace listener name to specify the trace file and options.

Enabling WCF Logging

You can create a WCF trace file with standard properties or set up a custom trace file.

To enable WCF logging

  1. Click the Diagnostics node.

  2. Click Enable Message Logging

  3. Click the Log Level link to adjust the log level. There are three log levels: Malformed, Service, and Transport.

  4. Click the listener name to specify the log file and options.
Note:
If you want the trace and message logs to be flushed automatically when your application is closed, enable the Auto Flush option.

The diagnostics Summary Page enables you to accomplish the most common tasks in configuring diagnostics. However, if you want to manually edit the Listeners and Sources settings, you must expand the Diagnostics node and edit settings in Message Logging, Listeners and Sources node.

Enabling WCF Custom Tracing or Message Logging

To enable WCF custom tracing or message logging

  1. Click the Diagnostics node, and expand it.

  2. Right-click the Listeners node and select New Listener.

  3. Enter the trace file name in the InitData field. You can click the “…” button to browse to a path.

  4. Clicking the TypeName line displays a "…" button. Click this button to open the Trace Listener Type Browser, which you can use to find preconfigured trace listeners that are already installed.

  5. Note the Source section. Click Add in this section to open a dialog box with a drop-down menu, which lists available tracing sources. Select a tracing source and click OK.

  6. To edit Message Logging settings, click the Message Logging node. You can edit the settings in the property grid.


Edit Behaviors Configurations

The Behaviors tab displays the behaviors that are currently defined in the configuration file.

Behavior configurations are used to configure behaviors of endpoints and services. Such configuration settings are stored in the Advanced node under Service Behaviors and Endpoint Behaviors. Service behaviors are used by services; whereas endpoint behaviors by endpoints.

Behaviors are a collection of extension elements that form a stack. The element at the top of the stack is applied first. Each extension element can have its own configuration.

Creating a new Behavior Configuration

You can create a new behavior configuration in the following ways:

  • Right-click one of the behavior nodes and select New Behavior Configuration…

  • Select one of the behavior nodes and click the New Behavior Configuration… in the Task Pane.

Adding Behavior Element Extensions to a Custom Binding

To add behavior element extensions to a custom binding

  1. Select one of the behavior nodes.

  2. Select the behavior you want edit.

  3. Click “Add”.

  4. From the list of available extensions, select the behavior element extension you want to add.

  5. Click “Add”.

Adjusting the Extension Position in a Custom Binding

Behaviors are collections of elements that form a stack. Each element on the stack has its own configuration. The order of the binding element extensions in a custom binding indicates their positions in the stack. Elements at the top of the stack are applied first.

To adjust the extension position in a custom binding

  1. Select one of the behavior nodes.

  2. Select the behavior you want edit.

  3. Select a behavior extension element in the Behavior Element Extension Position section.

  4. Use the “Up” or “Down” button on the left side of the list to change the position of the selected element.

Editing the Configuration of Behavior Element Extensions

To edit the configuration of the behavior element extensions

  1. Select one of the behavior nodes in the tree.

  2. Select the behavior that contains the element you want to edit

  3. Select the behavior element extension you want to edit. The settings of the element appear in the right pane where they can be edited.


Create or Edit Protocol Mappings

The ProtocolMapping section allows you to set default binding types for different protocols such as http, tcp, MSMQ or net.pipe via defined mapping between protocol address schemes and the possible bindings. You can also add new mappings to other protocols.


Manage Extensions

New binding extensions, binding element extensions, standard endpoint extensions and behavior extensions can be registered for use in WCF configuration. Extensions are name/type pairs. The name defines the name of the extension in configuration, whereas the type implements the extension. There are four types of extensions:

  • Binding extensions define an entire binding type. Example: basicHttpBinding.

  • Binding element extensions define an element of a binding. Example: textMessageEncoding.

  • Standard endpoint extensions define an entire standard endpoint. Example: discoveryEndpoint.

  • Behavior element extensions define an element of a behavior. Example: clientVia.

Extensions that have been registered in configuration can be used like any other WCF component of the same type.

Adding a New Extension

To add a new extension

  1. Select one of the extension nodes in the advanced nodes.

  2. Click New.

  3. Enter a name and type.

  4. Click OK.

  5. The extension now appears in the appropriate place in the Editor. For example, if you add a behavior element extension, it appears in the list of available extensions.


Create or Edit a Hosting Environment

This section allows you to defines instantiation settings for the service hosting environment.

Creating a Configuration File Using the Wizard

One way to create a new configuration file is to use the New Service Element Wizard. The wizard finds the installed service types and other elements compatible with WCF on the computer, including COM+ and Web-hosted virtual directories, and loads them to make creating the configuration much more streamlined.

Creating a configuration file

To create a configuration file

  1. Start Service Configuration Editor by using a command window to navigate to your WCF installation location, and then type SvcConfigEditor.exe.

  2. From the File menu, select Open and click Executable, COM+ Service, or WebHosted Service, depending on the type of configuration file you want to create.

  3. In the Open dialog box, navigate to the specific file you want to create a configuration file for and double-click it.

  4. In the File menu, point to Add New Item and click Service. The New Service Element Wizard opens.

    Note:
    If you want to use the NetPeerTcpBinding from the configuration file generated by the Wizard, you have to manually add a binding configuration element and modify the mode attribute of its security element to "None".


Create a New Configuration File

To create a new configuration file, use the New Service Element Wizard. The wizard finds the installed service types and other elements compatible with Windows Communication Foundation (WCF) on the computer, including COM+ and Web-hosted virtual directories, and preloads them to make creating the configuration much more streamlined.

Caution:
A service configuration file generated by the Configuration Editor is not guaranteed to be secure. Please refer to the Windows Communication Foundation Security documentation to find out how to secure your WCF services.

In addition, the Configuration Editor can only be used to read and write valid WCF configuration elements. The tool ignores schema-compliant, user-defined elements. It also does not attempt remove these elements from the configuration file or determine their effects on the known WCF elements. It is the user’s responsibility to determine whether these elements pose a threat to the application or the system.

Creating a Configuration File

To create a configuration file

  1. Start Service Configuration Editor (SvcConfigEditor) by using a command window to navigate to your WCF installation location and then type SvcConfigEditor.exe.

  2. From the File menu, select Open and click Executable, COM+ Service, or WebHosted Service, depending on the type of configuration file you want to create.

  3. In the Open dialog box, navigate to the specific file you want to create a configuration file for and double-click it.

  4. In the File menu, point to Add New Item and click Service. The New Service Element Wizard opens.

  5. Follow the steps in the wizard to create the new service.

Configuring COM+

The SvcConfigEditor enables you to create a new configuration file for an existing COM+ application, or edit an existing COM+ configuration. The COM Contract node is only visible when the <comContract> section exists in the configuration file.

To create a new COM+ configuration

  1. Before creating a new COM+ configuration, make sure that your COM+ application is installed in Component Services, and registered in the Global Assembly Cache (GAC).

  2. Select File menu -> Integrate -> COM+ Application. This operation closes the currently opened file. If there is unsaved data in the current file, a Save dialog appears. The COM+ Integration Wizard is then launched.

  3. In the first page, select the COM+ application from the tree. If you cannot find your COM+ application in the tree, verify if it is installed in the Component Services and registered in the Global Assembly Cache (GAC).

  4. In the next page, select which method(s) you want to expose as WCF services. All the supported methods in the COM+ application are displayed and selected by default.

  5. Choose a hosting method.

  6. Configure other settings according to the guides in the wizard.

  7. SvcConfigEditor utilizes ComSvcConfig.exe in the background to generate a configuration file. After this is completed, you can view a summary and exit the wizard. The generated configuration file is opened so that you can edit it directly.
To edit an existing COM+ configuration

  1. Select File menu -> Open -> COM+ Service…

  2. Select the COM+ Service you want to edit from the list.

  3. Edit configuration settings in the “COM Contracts” node.

Note:
You can also directly open and edit a configuration file which contains COM+ contracts.


Service Configuration Editor Resources

For more information about Windows Communication Foundation (WCF) configuration, see the following resources:

  • Windows Communication Foundation on the MSDN Web site.

  • Windows Communication Foundation Configuration Schema, which is a general reference of all WCF configuration elements.

  • Introduction to Building Windows Communication Foundation Services at the MSDN Library.

  • Class Library documentation for the .NET System.Diagnostics namespace at the MSDN Library.