Developing with SQLWindows

Chapter 1

DBPipe
For many years SQLWindows has allowed a WIN32 programmer to rapidly develop application connecting to databases (RAD). Team Developer 6.0 is the first version to introduce .NET, allowing you to build .NET WPF DESKTOP and BROWER applications. The opening of Team Developer SQLWindows to .NET introduced a new world of features in the product. One of the major features, strictly related to deployment, is the ability to create Web Browser applications using Microsoft XBAP ClickOnce Technology. It allows installation and execution (local) of a Windows application by clicking a link in a web page. It also addresses the complexity of updating a deployed application (Ref: http://en.wikipedia.org/wiki/ClickOnce). Unify DBPipe, also referred as AdoProxy/Database Proxy server, brought this feature a step further, allowing client application to connect to supported database without the need of installing any database client software. See the document: DotNet.PDF, WPF Applications p 3-2 and Publishing XBAP Applications p 4-1.

Developing with SQLWindows

1-1

Chapter 1

DBPipe

Team Developer 6.1 Unify DBPipe technology overview

Unlike WIN32 applications, DBPipe allows connection of a Team Developer .NET client application to supported databases without the need of having the database client installed on the client PC. This, along with a Web type XBAP application, greatly simplifies the deployment and update of Team Developer applications. This is made possible by the Microsoft Windows Communication Foundation (WCF) DBPipe using WCF as its core technology. In a nutshell, you can view DBPipe as a Web Service, servicing databases requests from a client to a server which is hosting that Web Service. WCF offers great performance and flexibility in hosting services along with offering multiple types of bindings (communication protocol) and security to support different connection type scenarios. Team developer 6.1 new features Hosting of a DBPipe server as a 1. Desktop EXE sever with a UI displaying database requests (simplifies debugging) 2. Windows Activation Service (WAS) with file logging 3. IIS (as it is the case already with Team Developer 6.0) Types of TD applications supporting DBPipe Team Developer 6.1 .NET Desktop EXE applications can now be a DBPipe client in the same way as Web Browser XBAP applications. This new feature, along using DBPipe server hosted as a Desktop EXE server, simplifies greatly the debugging and validation of an application requiring DBPipe. In other words, a Desktop EXE type application can now connect to any type of DBPipe server host. The same applies for XBAP type applications. Multiple BINDINGS now supported for different scenarios: - UnifyHttpService: No authentication required, use port 80. Scenario: internet access, intranet no domain - UnifyHttpSecureService: Windows authentication, use port 80. Scenario: intranet/ domain authentication - UnifyTcpService: No authentication required, use port 808, faster encoding than HttpService. Scenario: internet access, intranet no domain

1-2

Developing with SQLWindows

Team Developer 6.1 Unify DBPipe technology overview

The schema below shows the DBPipe components interactions. Each frame represents a machine: the DBPipe client, DBPipe Server and the database server machine. DBPipe Server machine (top frame) must have the database client installed. This machine can be an IIS HOST or any non IIS HOST running the DBPipe server. Typically, WINDOWS 2008 server would be used as a DBPipe server. The client can be any supported host client with no specific software installed (i.e.: a virgin machine). Only Microsoft .NET Framework 3.5 has to be installed if the client uses Windows XP. Windows 7/2008 provides the .NET Framework out of the box. The database server can be any existing host or can reside on the DBPipe server machine itself. Unify.TD.Runtime.Wcf.Provider.dll is a TD .NET assemblies used on the client side and makes the database request to Unify.TD.Runtime.Wcf.Server.dll. In this respect, we can view Unify.TD.Runtime.Wcf.Provider.dll as a generic .NET data provider, basically a client to the DBPipe server database.

Developing with SQLWindows

1-3

Chapter 1

DBPipe

1-4

Developing with SQLWindows

DBPipe Server side

DBPipe Server side

DBPipe technology is a client/server type of technology. Here is more details on how to setup/execute DBPipe server for the DBPipe client to make requests to it. The TD root directory after the installation will contain a DBPipeServer folder. This folder actually contains the DBPipe Server .EXE as well as the file needed to register DBPipe as a Windows Service.

DBPipe Server - Desktop Unify.DBPipe.Server.Deskop is actually the server executable with a User Interface. To start the server, simply launch it.

At the execution of DBPipe Server Desktop, a user interface will show up which allows us to see on what address the DBPipe server listens and what binding/

Developing with SQLWindows

1-5

Chapter 1

DBPipe

endpoints are configured. The terms bindings and endpoints are specific to WCF technology. Unify.DBPipe.Server.Desktop.exe.config This is the DBPipe Server Desktop configuration file and exposes different settings that can be changed: The port, timeouts and buffer sizes as shown in the green comments below.

1-6

Developing with SQLWindows

DBPipe Server side

NOTE: DBPipe Server Desktop uses the netTcpBinding bindings and can only use this type of binding. DBPipe Server IIS can use either ws2007HttpBinding, with or without security, or netTcpBinding. DBPipe Server - Window Service Unify.DBPipe.Server.WinSvc.exe is an installable Windows Service. To install DBPipe as a service execute the following command: %WINDIR%\Microsoft.NET\Framework\v2.0.50727\Installutil.exe Unify.DBPipe.Server.WinSvc.exe Installutil.exe is an executable part of the .NET Framework. After the install, notice the DBPipe Service showing in the service list. As usual start / stop the service as required or use net START/STOP DBPipe Service command.

Configuring and running the DBPipe Server Desktop or Service is simple compared to its IIS hosting. As long as the machine has a properly configured network interface and the .NET Framework installed, DBPipe server will run and listen to DBPipe request out of the box with no additional requirements. NOTE: Deploy61.EXE does not install DBPipe Server Desktop. Deploy61.EXE is meant for deploying a WIN32 application. To use DBPipe server on any supported machine is a simple matter of copying the DBPIpeServer folder from a Team Developer installation to the target machine, ensuring the .NET Framework 3.5 is installed on this host. DBPipe Server - IIS There is no specific installation folder in Team Developer for this type of hosting. The DBPipe server on IIS will be published/installed on IIS \inetpub\wwwroot from the Team Developer IDE PROJECT/PUBLISH menu.

Developing with SQLWindows

1-7

Chapter 1

DBPipe

See the document: DotNet.PDF, Publishing XBAP Application, p 4-1 for details. Once an initial DBPipe server is published on IIS, we can copy the published components on any other IIS host \inetpub\wwwroot\DBPipeServer and convert this folder to an application on the other IIS machine. This would constitute a manual DBPipe publishing. IMPORTANT: As expected, the machine where DBPipe IIS is published, either through TD publish feature or manually, needs to have the .NET Framework

1-8

Developing with SQLWindows

DBPipe Server side

installed. DBPipe IIS Server uses a WCF .SVC handler and IIS does not install/ register it by default. It must be installed/registered using the following command:

"%WINDIR%\Microsoft.NET\Framework\v3.0\Windows Communication Foundation\ServiceModelReg.exe" iru Since Team Developer DBPipe is a 32bit process, IIS must configure a 32 bit Application Pool when DBPipe Server is hosted on a 64 bit IIS server. See document: DotNet.PDF, Publishing XBAP Application, p 4-. The following snapshot shows the recommended setup/install of IIS on WINDOWS 7 64 bit allowing DBPipe Server IIS server to function properly. IIS WINDOWS 7 Installed along with Development feature. Note: All components shown here are not required, but recommended on a TESTING development machine.

WINDOWS 7 .NET Framework installed feature. The non HTTP Activation will be required when using net.tcp / UnifyTcpService types of binding on IIS.

Developing with SQLWindows

1-9

Chapter 1

DBPipe

IIS WINDOWS 7 64 bit: Setting Application Pool Default to 32bit.

1-10 Developing with SQLWindows

DBPipe Server side

WINDOWS 7 IIS console and default site having DBPipe Server published.

Developing with SQLWindows

1-11

Chapter 1

DBPipe

Testing DBPipe Server IIS / SVC handler: Here accessible and functioning, therefore properly configured.

1-12 Developing with SQLWindows

DBPipe Server side

DBPipe IIS Web.Config Unlike Team Developer 6.0, DBPipe Server IIS 6.1 can use either ws2007HttpBinding, with or without security, or netTcpBinding without security. Below is the default published Web.Config showing the default binding to be ws2007HttpBinding with security. Use windows credentials to connect is the new feature in Team Developer 6.1 IIS publisher allowing domain authentication as it is the case in TD 6.0. TD 6.1 publisher allows turning off authentication when it is required. The default binding published then is ws2007HttpBinding (without security) but can be changed manually to netTcpBinding.

Developing with SQLWindows

1-13

Chapter 1

DBPipe

The following snapshot shows the default .Config files as published on IIS. Uncomment to the desired bindings.

Below shows the type of authentication and the specific SQLBase setting used to specify the path of the SQLBase API (needed only when using SQLBase from a TD development environment).

1-14 Developing with SQLWindows

DBPipe Client side

DBPipe Client side

Having covered the server side, lets now focus on the connection of the DBPipe client. A DBPipe client can only be a TD .NET Desktop EXE application or an XBAP application. We cannot use this technology if we are targeting a WIN32 TD application. .NET EXE application connecting to DBPipe Server -Desktop As already stated, one of the changes from Team Developer 6.0 is that now version 6.1 allows a .NET EXE application to use any type of DBPipe Server. This is achieved by generating a default DESKTOP.EXE.config upon compilation. This config file contains the needed information to connect to any previously described DBPipe Server. Lets show an example of this by loading Team Developer 6.1 and creating / building a minimalistic myDesktopApp.app that simply exposes a form connecting SqlConnect() to SQLServer and confirm the connection to the database using SalMessageBox(). When building the application as a .NET EXE target, Team developer will generate the following default file (XML format) myDesktopApp.exe.config. It contains the information shown below (not in the order of the generated file for the purpose of our description). ADDRESS: The endpoint address URL that specify the address of the DBPipe server. Here we can change the IP address and PORT as required to access a DBPipe Server Desktop running either locally or remotely. Client endpoint: Default uses the netTcpBinding/UnifyNetTcpService as this is what the DBPipe Server Desktop uses (see previous description of DBPipe Server Desktop). If we dont want to use DBPipe Server Desktop but want to use DBPIpe IIS Server, we can change the bindings to use ws2007HttpBinding since the default of this server is ws2007HttpBinding ( see DBPipe IIS Web.Config section)

Developing with SQLWindows

1-15

Chapter 1

DBPipe

BINDINGS: DBPipe client currently supports two types of bindings that are defined below. The client endpoint node displayed previously might use one or the other binding. There is nothing that needs to be changed here in the bindings, unless we want to tweak/ experiment with buffer sizes and timeouts. See comments in the Unify.DBPipe.Server.Desktop.exe.config pertaining to buffer size. NOTE: WCF supports multiple kinds of bindings. Unify currently only supports the two described previously. We cannot change the server/client .config file attempting to use any other bindings from WCF. This is because Unify DBPipe server and client assembly needs to specifically support them internally.

1-16 Developing with SQLWindows

DBPipe Client side

Application settings UseRemoteConnections: As the XML comments below show, this is where we can tell a client application to use (or to not use) a DBPipe Server connection. Auto (for backward compatibility) is the default settings, meaning that if we do have our database client installed on the machine that runs the TD client application it would NOT use DBPipe but use the database connectivity installed on that machine to connect to the database. When developing a TD application, the database clients are set up on the development machine. Use true on a development machine to actually TEST/VERIFY connectivity to a DBPipe server at runtime. The preference is to use a localhost DBPipe running Server, as it is simpler to set up and offers logs from its UI.

Developing with SQLWindows

1-17

Chapter 1

DBPipe

NOTE: When debugging a .NET application in the Team Developer IDE debugger, DBPipe is bypassed.

1-18 Developing with SQLWindows

Web Browser XBAP application connecting to DBPipe Server - Desktop

Web Browser XBAP application connecting to DBPipe Server - Desktop

Since Team Developer 6.0 it is possible to create .NET WEB Browser application. See document: DotNet.PDF, Publishing XBAP Application, p 4-1. One of the differences betweem TD 6.1 and TD 6.0 is that the default setting with 6.1 is to use the DBPipe Server Desktop instead of using DBPipe Server IIS as was the case in the 6.0. This can be easily tested without the need of an actual IIS server: - Create a simple TEST application just doing a SqlConnect() to SQLServer as an example. - Select the build setting to be a .NET WPF Browser (XBAP) target - Compile / build the .EXE

Team developer generates the needed files: .config file, .exe, .xbap and .manifest. Note: The .config file of an XBAP build is exactly the same as the one that generated by a build of a .NET EXE application (see previous section comments regarding the config file of a .NET EXE build).

We can directly test the generated application by executing (double click in explorer) the XBAP file without the need of publishing it on an IIS server. This will open the Web Browser, install the application and execute it in our browser. If the machine we execute the XBAP application has the connectivity to SQLServer installed and properly set up, the XBAP application will connect transparently and will not use any DBPipe Server. This is because the default (backward compatibility) is to use local database connectivity: UseRemoteConnections="Auto".

If we want to test/access the DBPipe Server Desktop we will have to make the following changes: - Edit the initially generated .config file and change to UseRemoteConnections="true". - Rebuild the application again in TD after the above change of the .config setting. This is necessary for regenerating the manifest/xbap file. Notice that the altered .config file will not change after the rebuild.

Developing with SQLWindows

1-19

Chapter 1

DBPipe

- Execute DBPipe server in TDINSTALLDIR\DBPipeServer\Unify.DBPipe.Server.Desktop.exe. This will run an instance of DBPipe Server Desktop, exposing the UI showing any incoming connections from a client. - Execute TEST the XBAP

IMPORTANT: When publishing an XBAP application on IIS: Every change made to a TD XBAP application requires an increment of its version in the build setting and then a republish, else the browser upon execution of the application might give an error: Unable to install this application because an application with the same identity is already installed. If you dont want to change the version you can clear the XBAP installed cache using - mage.exe cc (This is a .NET Framework command) -or rundll32 dfshim CleanOnlineAppCache

This snapshot shows a simple test TD XBAP connecting application running locally and connecting to SQLSEVER via DBPipe Desktop .EXE sever. Notice the incoming ODBC connection in the UI of the server.

1-20 Developing with SQLWindows

Web Browser XBAP application connecting to DBPipe Server - Desktop

Developing with SQLWindows

1-21

Chapter 1

DBPipe

.NET application connecting to DBPipe IIS Server

If we want to use DBPipe Server hosted on IIS, we need to change the client application .config file, regardless if we want to use a .NET EXE or XBAP application. Below are the basic steps:

- Ensure the access to an IIS server and that all the needed components are installed / configured as shown in DBPipe Server IIS section. - Publish DBPipe IIS Server (Database proxy Server) from the TD PROJECT/ PUBLISH menu as explained in DBPipe Server IIS section - Make sure DBPipe IIS Server SVC handles is accessible and functional as explained in DBPipe Server IIS section. - Change the .NET client application .config file to match the default settings of DBPipe IIS server as explained below.

As discussed previously, DBPipe IIS server default uses the ws2007HttpBinding with security. Since .NET applications EXE or XBAP (clients to DBPipe Server) uses the netTcpBinding without security, the client exe.config needs to be changed to access DBPipe server. In other words, a client configuration must match the server configuration. Manually editing and changing of the client .config file is required for TD .NET EXE and XBAP applications. For desktop EXE applications just edit the .config file and directly test/execute the .EXE. For XBAP applications, make an initial build to generate the necessary files then edit the .config and publish your change (changes of the .config will not be lost as explained earlier). Whenever you make changes in any of the settings re-publishing is required for the MANIFEST/XBAP to take into account the changes.

IMPORTANT: A direct change of the published .deploy files on IIS is not allowed. Doing so would give an error executing XBAP application stating that the manifest has a Hash error.

Uncomment the below default .config Client endpoint node generated from an XBAP or an EXE build to use ws2007HttpBindings matching the server configuration in order to access DBPipe IIS server 1-22 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server

If testing on a development machine, ensure UseRemoteConnections="true" to enforce connection to a DBPipe Server and not the use of the local DB clients access. When IIS is running, the DBPipe IIS server is published and accessible and the endpoint of the client changed to match the DBPipe server config , we should be able to connect as shown below.

Developing with SQLWindows

1-23

Chapter 1

DBPipe

Stopping the IIS server while a TD DBPipe client application attempts to access DBPipe IIS server would return the following error.

1-24 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server

Developing with SQLWindows

1-25

Chapter 1

DBPipe

DBPipe Server Log

DBPipe Server allows incoming connections and SQL Transactions to be logged. The real time log in the DBPipe sever Desktop UI can be seen at different levels or toggled off. DBPipe Sever Desktop offers the easiest way of debugging and validating a Team Developer DBPipe client application. The snapshot below shows an XBAP application connecting to DBPipe Server Desktop with LOG feature enabled and set to verbose

When using DBPipe Server IIS or DBPipe Server Desktop installed as a Windows service, logs can be enabled by setting the following environment variable: DBPIPE_EVENT_LOG : log file name, i.e. C:\log\DbPipe.log DBPIPE_LOG_LEVEL : 0: Off, 1: Error, 2: Warning, 3: Info, 4: Verbose

NOTE: Logs are not currently logged in the Windows Event log.

1-26 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

.NET application connecting to DBPipe IIS Server over the internet

We will show how to set up DBPipe IIS Server to use netTcpBinding and how to configure an XBAP application to its server setting, so to execute an XBAP application using DBPipe over the internet. With TD 6.0 this was not possible. This is not because XBAP applications on standard port 80 are not traversing a firewall through port forwarding, but because DBPipe 6.0 requires authentication on a domain. Hence using TD 6.0 DBPipe on a LAN using WORKGROUP was also not possible in TD 6.0. Team Developer 6.1, its new publishing features and bindings choices allow you to disable authentication and also allows uses of other better-performing bindings, such as netTcpBindings. We can still use ws2007HttpBinding without security, unchecking use Windows credential and go over the internet just fine. Here is what needs to be done to change the bindings to use the better-performing netTcpBinding: net.tcp protocol installation & configuration for DBPipe IIS server Below shows the required .NET Framework 3.5.1 components on Windows 2008 server. All features should be installed, especially the Non-HTTP Activation for net.tcp usage.

Developing with SQLWindows

1-27

Chapter 1

DBPipe

On Windows 7, the below snapshot was already shown in the DBPipe Server IIS section.

1-28 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

As usual, when using DBPipe Server IIS, always ensure the SVC handler is registered and that the default application pool is set to 32bit as it was explained in the DBPipe Server IIS section.

*.SVC showing enabled on WIN2008 IIS Server.

Developing with SQLWindows

1-29

Chapter 1

DBPipe

Next, on our default site we have to add the net.tcp binding by editing the default site binding from the context menu and entering the following information.

1-30 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Having already published an initial version of DBPipe on IIS, simply copy the folder found in \inetpub\wwwroot\DBPipeServer to \inetpub\wwwroot\DBPipeServer\DBPipeServer.NetTcp as an example. Any name is fine. Since this is a WCF service, right click DBPipeServer.NetTcp in IIS console and convert to application from the context menu. Once this is done from the right pane advanced setting In the Behavior, add net.tcp protocol as shown below.

Developing with SQLWindows

1-31

Chapter 1

DBPipe

At this point, you can edit the Web.Config from DBPipeServer.NetTCP and change the bindings from ws2007HttpBinding to netTcpBinding by commenting ws2007HttpBinding and un-commenting netTcpBinding endpoint.

1-32 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Now we are ready to test our DBPipe IIS server configured for netTcpBinding by giving its URL. This would work for the URL shown below (assuming that the server is up and running). Here we are good to go.

Developing with SQLWindows

1-33

Chapter 1

DBPipe

IMPORTANT: If testing is done over the internet, dont forget to open port 808 on your machine firewall and on the router make a port forwarding from any incoming address on port 808 to your LAN host IP address. If all works fine at this point, we are ready to focus on either a TD .EXE or XBAP client application. All that needs to be done is matching the client .config to the server config as well as giving the public IP address of your router as an endpoint. All this was already covered in the previous sections. Here is an example of a client .config accessing DBPipe IIS Server over the internet using netTcpBinding.

1-34 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

The WPFDemo sample over the internet, the application would run just fine as an example on virgin Windows XP machine having ONLY the .NET Framework installed.

Team Developer SQL.INI in the context of .NET and DBPipe There are no differences in the way we configure a SQL.INI to connect to the supported database. This is done exactly the same way for .NET as for WIN32. The same applies for .NET EXE or XBAP applications whether using DBPipe or not. 1-35

Developing with SQLWindows

Chapter 1

DBPipe

Changing published XBAP components without re-publishing When we want to change the .config of an existing published application, i.e. the endpoint IP address, we can use Team Developer to republish the changes. As previously explained, changes done to the config file are maintained when republishing. However, this requires access to the development machine to re-publish the application. It is not possible to make direct changes in XBAP application already published. Doing so and executing the XBAP would give a manifest Hash error as we tampered with the IIS deployment files of the XBAP published app and the manifest no longer matches the XBAP. Using MAGEUI.EXE .NET tool we can re-generate a proper manifest and XBAP file after having edited directly in IIS, inetpub\wwwroot\test as an example; the test.config.deploy file or the sql.ini.deploy files. Here is how: Edit the working published .config.deploy and alter, as an example, UseRemoteConnections (default auto) to true. -Execute the XBAP application in your browser. You should get a Manifest Hash Error -Launch mageui.exe and drag and drop into it the .manifest.deploy and .manifest.xbap

1-36 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

At this point, we can delete the .manifest.deploy and .manifest.xbap in our IIS deployment directory. Notice the version information. This can be changed if, for example, we need to deploy multiple versions of an XBAP application, changing only the bindings. We would just have to copy the original TD deployed XBAP application to another folder name in the IIS inetpub\wwwroot directory, change its directory name and convert it to an application. We then use mageUI to change the version so to allow both the original version and the new one (with an altered .config) to run as two separate applications.

So in our task of changing UseRemoteConnections from auto to true, already done in previous step, lets also change the version to version 3.3.3.3.

Developing with SQLWindows

1-37

Chapter 1

DBPipe

Notice also some other important section in the manifest, i.e. files showing what component is deployed. Here we can remove any unwanted deployed files.

1-38 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Another important setting is what the application security defines in the permission set type. XBAP application needs a certificate to support full trust as this is the default setting for TD XBAP applications. This means that the XBAP application can fully access any resources, file I/O etc. Thus a TD XBAP application requires trust certificate to be installed in proper stores.

Developing with SQLWindows

1-39

Chapter 1

DBPipe

Once we are finished altering any settings, save the manifest file.

1-40 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Because the XBAP application defines a FULL trust we will be required to sign the manifest with a certificate. The certificate is the certificate that was already deployed by TD. So just select xbap_key.pfx, its password being 12345. Once saved, notice that a new manifest file was created.

Now display the XBAP TAB previously opened in mageUI.

Developing with SQLWindows

1-41

Chapter 1

DBPipe

Notice again its version. An XBAP file is linked to a manifest (our previously recreated manifest file).

Now select Application Reference in mageUI.

1-42 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Click Select manifest and select the previously generated manifest. Now the XPAB is linked to our version 3.3.3.3 previously generated manifest.

Developing with SQLWindows

1-43

Chapter 1

DBPipe

At this point go back in the Name section of and change the version of the XBAP to be 3.3.3.3 matching the previously generated manifest.

Now save the XBAP to re-create it. Use the already deployed xbap_key.pfx for the certificate, its password being 12345. We are now done. Both a new manifest and xbap file were re-created by MageUI. We can now execute the XBAP application in our browser with the changes in place.

1-44 Developing with SQLWindows

.NET application connecting to DBPipe IIS Server over the internet

Developing with SQLWindows

1-45

Chapter 1

DBPipe

1-46 Developing with SQLWindows