Installing and running the Out-of-Process Windows Service/Console Host

  • Article

patterns & practices Developer Center

This topic explains how to obtain, install, and run the Semantic Logging Out-of-Process Windows Service/Console Host (Out-of-Process Host), and how it can be reconfigured dynamically at runtime.

Installing the Out-of-Process Windows Service/Console Host

The Semantic Logging Out-of-Process Windows Service/Console Host (Out-of-Process Host) is a component of the application block that you can use to collect and process trace messages from an application running in a different process on the same computer. You install the Out-of-Process Host on each computer where you want to collect events, and configure it to send these events as log messages to your chosen logging destinations.

Note

For more information about working with the Out-of-Process Host, see Using the trace event service for the out-of-process scenario.

You can install the Out-of-Process Host from NuGet, or download it from the CodePlex community site and install it.

To install the Out-of-Process Host from NuGet

  1. Open or create a Visual Studio project or solution on the computer where you will run the Out-of-Process Host.
  2. Open the NuGet Package Manager and search online for semantic logging service.
  3. Select the Semantic Logging Application Block - Out-of-process Service and choose Install.
  4. Review and then accept the license terms by selecting I Agree. After the installation is complete, close the package manager dialog.
  5. Open a command prompt as an administrator and navigate to the subfolder \packages\EnterpriseLibrary.SemanticLogging.Service.version\tools\ in your solution folders.
  6. Run the install-packages.ps1 PowerShell script to install the dependencies for the Out-of-Process host.
  7. At the command prompt, type SemanticLogging-svc.exe -install to install the service using the Local Service account. If you want to use a different account, use the -account command line switch instead (see the table below for details of all of the command line switches). Alternatively, type SemanticLogging-svc.exe -start to install and start the service.
  8. If you did not start the service when you installed it, open the Services console in Control Panel and select the service Enterprise Library Semantic Logging Out-of-Process Service. On the context menu, click Start to start the service.

To download and install the Out-of-Process Host from CodePlex

  1. Download the distribution zip file for the Out-of-Process Host (SemanticLogging-svc) from the Semantic Logging community site on CodePlex at https://aka.ms/slab-downloads.
  2. In Windows Explorer, open the folder where you downloaded the distribution zip file and select it. Open the context menu and choose Unblock.
  3. Extract the contents of the zip file to the computer where you intend to run the Out-of-Process Host.
  4. Read the license and the readme text files for the latest information about the Out-of-Process host, and the terms for using it.
  5. Open a command prompt as an administrator and navigate to the folder containing the files extracted from the downloaded zip file.
  6. Run the install-packages.ps1 PowerShell script to install the dependencies of the Out-of-Process host.
  7. At the command prompt, type SemanticLogging-svc.exe -install to install the service using the Local Service account. If you want to use a different account, use the -account command line switch instead (see the table below for details of all of the command line switches). Alternatively, type SemanticLogging-svc.exe -start to install and start the service.
  8. If you did not start the service when you installed it, open the Services console in Control Panel. Then find the service Enterprise Library Semantic Logging Out-of-Process Service. On the context menu, click Start to start the service.

Note

If there is an exception when the service starts, you may need to edit the permissions in Windows Registry for the service. See the section Errors when the Out-of-Process Host service starts below for more information.

The executable file SemanticLogging-svc.exe supports the following command line switches.

Command line switch

Details

-a, /a, or -account

Runs the installation under a specified account context. Syntax is:

-a=type or -account=type where type is User, LocalSystem, or LocalService. The default is LocalService.

-c, /c, or -console

Runs the executable as a console application. This is useful for testing your logging strategy and the service configuration. You can use the Console sink to view event messages in the console. It also displays any configuration errors in the Console window.

-h, /h, -help, or -?

Displays help information.

-i, /i, or -install

Installs the service.

-s, /s, or -start

Starts the service running if it is already installed. Starts and installs the service if the service is not yet installed.

-u, /u, or -uninstall

Uninstalls the service.

Alternatively, you can use the installutil utility to install and uninstall the service. For information, see Installutil.exe (Installer Tool) on MSDN.

Running the Out-of-Process Windows Service/Console Host

By default, the Out-of-Process Host application uses a configuration file named SemanticLogging-svc.xml located in the same folder as the application. You can use a different configuration file by editing the app.config file and changing the value of the EtwConfigurationFileName key. For more information, see Using the trace event service for the out-of-process scenario.

You must ensure that the Out-of-Process Host application is running to collect events. By default, it is installed with its startup type set to Manual. You can start it manually or configure it to start automatically with the operating system by setting the service properties in the Services console in Control Panel.

Errors when the Out-of-Process Host service starts

The Out-of-Process Host requires permission to update the following Windows registry key:

HKEY_LOCAL_MACHINE

\Software

\Microsoft

\Windows

\CurrentVersion

\Winevt

\Publishers

In some cases, such as where local or domain security policies have been changed from the default, this permission may not be available. This can cause an exception when the Out-Of-Process Host starts. To resolve this you must change the permissions on this key.

Note

Using Registry Editor incorrectly can cause serious, system-wide problems that may require you to re-install Windows to correct them. Changes made to the Windows registry happen immediately, and no backup is automatically made. Do not edit the Windows registry unless you are confident about doing so.

To set the required permission for the Out-of-Process Host in Windows Registry

  1. Run regedit.exe and navigate to the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Winevt\Publishers.
  2. Select this key in the tree-view list, open the Edit menu, and choose Permissions.
  3. In the Permissions for Publishers dialog, choose the Advanced button.
  4. On the Permissions tab page of the Advanced Security Settings for Publishers dialog, choose the Add button.
  5. In the Permission Entry for Publishers dialog, choose the Select a Principal link at the top of the page to open the Select User, Computer, Service Account or Group dialog. In this dialog, enter the name of the account that the Out-of-Process Host is running under. This is likely to be SYSTEM, LOCAL SERVICE, or your own user account depending on the option you specified when you installed the service.
  6. Use the Check Names button to validate the account name, and then choose OK to close the Select User, Computer, Service Account or Group dialog.
  7. Back in the Permission Entry for Publishers dialog select Allow in the drop-down list for Type, and select This Key and subkeys in the drop-down list for Applies to.
  8. In the Basic permissions list, ensure that the checkbox for Special permissions is checked and choose the Show advanced permissions link in this section of the dialog.
  9. Ensure that the three checkboxes named Set Value, Create Subkey, and Read Control are checked.
  10. Choose OK to close each of the dialogs and then close the Registry editor.

Next Topic | Previous Topic | Home | Community