Publishing and Connecting to the StreamInsight Server

Article
07/28/2016

In a StreamInsight client program, you can choose to use an embedded StreamInsight server in-process or connect to a remote server. In both cases, you use a server object to create a StreamInsight application and define entities such as an event source and sink. In order to connect to a remote server instance, the hosted StreamInsight server must expose the Web service manageability interface.

Connecting to a Server

When hosted in-process, the StreamInsight server is created through the following call:

Server server = Server.Create(…);

Alternatively, the StreamInsight client can connect to a remote server that runs as a separate process. In the following example, a client connects to a server identified by a specific end-point address.

Server server = Server.Connect(new System.ServiceModel.EndpointAddress(@"https://localhost/StreamInsight/MyInstance"));

This example connects to an installed StreamInsight service with the instance name "MyInstance." Note that in order to connect to any StreamInsight server (an installed service or your custom server application), the connecting user must be in the group corresponding to the server instance. For more information about this group and the StreamInsight service, see Installation (StreamInsight).

Exposing the Server End Point

For the Connect() method to succeed, the remote server must expose its manageability interface through a Web service end point at the given uniform resource identifier (URI). For example, the StreamInsight Event Flow Debugger is a client application that, when connected to an end point of a live server, can retrieve diagnostic information about queries and other server-level objects or record events from a running query for further debugging.

If you configured a StreamInsight Host Windows service when you installed StreamInsight, then you can connect to that service as a remote server. An application can expose the manageability interface of a hosted StreamInsight server by adding a Web service end point as shown in the following example. The example assumes that a registered StreamInsight instance named "MyInstance" exists.

Server server = Server.Create("MyInstance");  
ServiceHost host = new ServiceHost(server.CreateManagementService());  
host.AddServiceEndpoint(typeof(IManagementService),  
                        new WSHttpBinding(SecurityMode.Message),  
                        "https://localhost:8090/MyStreamInsightServer");  
host.Open();  
...  
host.Close;

Note that you must add a reference to the Microsoft.ComplexEventProcessing.ManagementService.dll and specify the corresponding namespace in order to use the Management Service.

StreamInsight uses Windows Communication Foundation (WCF) for its Web service interface. A full discussion of WCF configuration is beyond the scope of this documentation, but consider the following points when exposing the Web service:

The binding to the specified URL requires this URL to be reserved for the user account that executes the application. If the StreamInsight application is not executed under administrator rights, the following command must be run in an elevated command shell:
```
netsh http add urlacl url=http://+:8090/MyStreamInsightServer user=<domain\userid>  
```
The URL reservation through netsh always requires a port name to be given. Choose a port that has not been already used. Use the following command to list the URLs that are currently reserved.
```
netsh http show urlacl  
```
Note that the use of wildcards in the URL reservation has an effect on the HostNameComparisonMode parameter in the binding. The default matching mode of a binding is StrongWildcard. If, for example, you want to enable exact host name matching (using "localhost" in the endpoint specification of the server, and only allowing local clients to connect), you first must set the corresponding matching mode:
```
WSHttpBinding binding = new WSHttpBinding(SecurityMode.Message);  
binding.HostNameComparisonMode = HostNameComparisonMode.Exact;  
host.AddServiceEndpoint(typeof(IManagementService),  
        binding,  
        "https://localhost:8090/MyStreamInsightServer");  
```
Like any other WCF property, this can also be specified in the app.config.

Then, you also must reserve the corresponding URL scope by using the netsh command:
```
netsh http add urlacl url=https://localhost:8090/MyStreamInsightServer user=<domain\userid>  
```
In the previous example, the end point configuration is specified programmatically. Alternatively, the end point can be configured through an app.config file like any other application that is based on WCF. The installed StreamInsight service, for example, makes use of such a declarative configuration for each registered instance. The configuration file can be found under the StreamInsight installation folder under Host\<instance_name> called StreamInsightHost.exe.config.
On Windows XP and Windows Server 2003, netsh is not available. Instead, you must install the Windows Server 2003 support tools and use the httpcfg command from "<drive>:Program Files\Support Tools\” to reserve URLs. For example, the command to reserve a wildcard URL for the network service account, is:
```
httpcfg set urlacl /u http://+:80/StreamInsight/MyStreamInsightServer /a "D:(A;;GX;;;NS)"  
```

When exposing the Web service for connections across the network, consider the following specific information.

The installed StreamInsight service only allows local connections by default. When you must expose the Web service of the installed service to machines other than localhost, you must follow the steps outlined above to:
1. Change the URL reservation for the service from the explicit "localhost" to the wildcard "+".
2. Change the host name matching in the app.config of the service to StrongWildcard.
When enabling remote connections, the specified port must be opened in the firewall of the server.
When connecting a client to a remote server instance across the network using the machine name, Kerberos is used to authenticate instead of NTLM when using the IP address. This means that the client needs to set a user principal name (UPN) identity for the endpoint before connecting:
```
EndpointIdentity ei = EndpointIdentity.CreateUpnIdentity(WindowsIdentity.GetCurrent().Name);  
EndpointAddress ea = new EndpointAddress(new Uri(@"http://machinename:8090/MyStreamInsightServer"), ei, (AddressHeaderCollection)null);  
server = Server.Connect(ea);  
```

Consult the WCF documentation for further details about specifying endpoints.

Publishing and Connecting to the StreamInsight Server

Connecting to a Server

Exposing the Server End Point

See Also

Additional resources