OutSystems Platform 8 - The Detach Process for .NET

© 2001- 2013 OutSystems - All rights reserved www.outsystems.com / 11

Table of Contents1 How the Agile Platform Structures the Generated Code .........................................................................................................2

2 Detaching the Source Code .............................................................................................................................................................3

3 Preparing the server to deploy the Generated Code ................................................................................................................5

3.1 Using the Application Server that Previously Hosted the OutSystems Platform ......................................................................................................... 5

3.2 Using a Brand New Application Server ....................................................................................................................................................................................... 7

4 Compiling and Deploying Applications to IIS .............................................................................................................................8

5 Additional Steps ............................................................................................................................................................................... 10

5.1 Dependencies .................................................................................................................................................................................................................................. 10

5.2 Extensions ......................................................................................................................................................................................................................................... 10

5.3 OutSystems Scheduler Service ................................................................................................................................................................................................... 10

5.4 Microsoft Excel Files ....................................................................................................................................................................................................................... 10

5.5 Database Configuration ............................................................................................................................................................................................................... 10

5.6 Encrypted Configuration Data ................................................................................................................................................................................................... 11

This document is a step-by-step guide for extracting the source code of your applications fromthe .NET version of the OutSystems® Platform and how to set it up to be executed andmaintained independently of the OutSystems Platform, if you ever decide to detach from it.

This is a complement to the OutSystems Platform – Standard Architecture with No Lock-intechnical note that gives a high-level view on how the OutSystems Platform, unlike otherproprietary technologies and frameworks, generates standard, optimized, and fullydocumented .NET source code that does not require runtime interpreters or engines.

TECHNICAL NOTE

OutSystems® Platform 8The Detach Process for .NET

http://www.outsystems.com/res/TechnologyIndependenceTechnicalNote


1 How the Agile Platform Structures the Generated CodeWhen you deploy an application module (eSpace) using 1-Click Publish operation, a standard .NET application isgenerated by the OutSystems Platform Compiler.

The code is structured in the following folders:

DAAB – contains the Data Access Application Block to allow accessing database data.

GemboxSpreadSheet – contains the .NET component which enables developers to write, read or convertspreadsheet files (XLS, CSV, XLSX, HTML or ODS) from their .NET applications.

ICSharpCode.SharpZipLib – contains the SharpZipLib which is a .NET compression library used by thegenerated applications.

OutSystems.RuntimeCommon – contains the basic runtime code used by all runtime libraries and eSpaces.

< Project Name> – contains the eSpace’s source code.

< Project Name>ReferencesProxy - contains the source code to access referenced elements specified in othereSpaces.

RuntimePlatform – contains the Platform’s runtime code used by the eSpace.

SMSInterface – contains the runtime code to deal with SMS.

WebWidgets – contains the runtime code for the various custom web controls

Figure 1: Code Structure of a generated Application.

In the application folder (<Project Name>) you will find a set of sub-folders that group, under a single module,the code generated by the OutSystems Platform for all elements of your eSpace. These folders are:

Actions – contains the generated code of all User Actions and User Functions defined in your eSpace and thePlatform’s Built-in Actions.

Blocks – contains the generated code of all the Web Blocks defined in your eSpace and the Platform’s Built-inWebBlocks

Entities – contains the code to manage all Entities defined in your eSpace.

Structures – contains the code to manage all Structures defined in your eSpace.

ProcExc<ProcessName> – contains the generated code of all Processes defined in your eSpace.

Exceptions – contains the declaration of all user defined Exceptions.

Roles – contains the code to support role based security enforcement.

TypeFactory –contains the code used by consumers of the eSpace so they can access the referred elements.

WebServices – contains the code to support all Web Services exposed by your eSpace.

WebReferences – contains the code to support all Web References consumed by your eSpace.


2 Detaching the Source CodeTo obtain the source code of an eSpace (application module), open the Licensing page under the Administrationtab in Service Center and detach the source code as follows:

1. Click on ‘eSpaces Source Code’.

2. Click on ‘Detach’ for the eSpace that you want to obtain the source code.


3. Wait until the OutSystems Platform has finished packing the eSpace source code and click on ‘Download’.

4. Save the zip file in a folder of your choice.

5. Unpack the zip file to get your source files (organized in folders).

Do you want to evaluate the detach source code process?

For the purpose of evaluating the detach source code process, OutSystems provides a ServiceStudio embedded tutorial to guide you through the process. In Service Studio, in the OutSystemstab, you can find the ‘No Lock-in’ how-to.

The steps described in this section are not enabled for evaluation purposes and will only be fullyavailable if you decide to stop using the OutSystems Platform.

Please refer to the first chapter of the OutSystems Platform – Standard Architecture with NoLock-in technical note for more information.




3 Preparing the server to deploy the Generated Code

3.1 Using the Application Server that Previously Hosted the OutSystemsPlatform

Before you open the application’s solution in Visual Studio make sure that no eSpace publication has occurred inthe local machine or otherwise you will get errors; check for any existing eSpace publication data in the InternetInformation Services (IIS) and clear it out as follows:

1. Open the Windows Control Panel in your Windows Start Menu.

2. Click on the Administrative Tools item to list the System Configuration Tools.

3. Double-click on the Internet Information Services (IIS) tool to open its management window.

4. In the left pane tree expand the following items:

1. ‘<your machine name>’

2. ‘Sites’

3. ‘Default Web Site’


4. Look for a virtual directory with the same name as your published eSpace and remove it; either byclicking on it and then pressing the Del key, or by right-clicking on it to open the popup menu andthen choosing the ‘Remove’ option.

Now you should be able to open your application’s solution (.sln file) in Visual Studio without any problems.


3.2 Using a Brand New Application ServerIf you want, you can deploy your eSpace in a brand-new server where you never installed the OutSystems Platform.To do this, you must first setup the server with the needed configurations, as if you were installing the OutSystemsPlatform, but skip the OutSystems Platform itself.

Note that, to do this, you will need to either decommission the OutSystems server, or get a database copy to usewith the new server.

Proceed as follows:

1. Install IIS component (as described in the install checklist). If you want to use Visual Studio remotely (from aworkstation) install also Frontpage Extensions;

2. Install .NET Framework 2.0 Service Pack 2 or above and configure it for use with IIS. Use the instructions inthe install checklist;

3. Install Message Queuing component. Use the instructions in the install checklist;

4. Configure Windows Management Instrumentation service.

5. Configure the Default Web Site in IIS to use .NET Framework 2.0;

6. Update the data model in the OutSystems server:

a. Update OSSYS_SERVER entity. Replace new_hostname with the output of the hostnamecommand in a command line.

update ossys_serverset name = 'new_hostname'where name = 'old_hostname'

b. Update OSSYS_PARAMETER. . Replace new_hostname with the output of the hostnamecommand in a command line (in the new server) and old_hostname with the output in the oldserver. C:\Windows\Temp represents a path where any user can write – it can be replaced byanother, if needed.

update ossys_parameterset host = 'new_hostname'where host = 'old_hostname'

update ossys_parameterset val = 'C:\Windows\Temp'where name = 'Cache.ControlPath' and host = 'new_hostname'

7. Prepare machine.config with the appSettings (see topic 5.5 below for details)

8. Configure the DefaultAppPool to run as Local System. This is needed at least for first-time run, since somesettings are written in the registry.

9. Copy the custom handlers in the OutSystems OutSystems Platform server (C:\ProgramFiles\OutSystems\Platform Server\customHandlers) to the new server, and create a Virtual Directory in IIS,named customHandlers, with the files. Make sure to specify language vb for this Virtual Directory.

http://www.outsystems.com/NetworkDocuments/DocumentDetail.aspx?DocumentId=764&VirtualDirectoryId=68


4 Compiling and Deploying Applications to IISIn order to deploy applications to IIS, you will need Visual Studio 2008 or 2010 (if using Express, you need WebDeveloper and Visual C# components). To deploy your applications, proceed as follows:

1. Open the <Project Name>.sln file. If using Visual Studio Express, choose Web Developer option.

2. Execute the Visual Studio’s Build Solution command to compile your application.

3. Execute the Visual Studio’s Publish <Project Name> command to publish your application to IIS:

4. In IIS (see section 3.1), find a virtual directory with the name of your published eSpace and click on it.

5. Double click on the ‘Default Document’ icon.


6. In the right pane click on the ‘Add…’ link.

7. Type ‘_Default.aspx’ for the document name and press ‘OK’.

After this step, your application is ready to be used in the new server.


5 Additional Steps

5.1 DependenciesIt is likely that your application depends on other applications. If that is the case, you should deploy them all to besure that you bring all the needed components (particularly, if there are links between applications). To do that, youneed to detach and publish each one individually using the instructions in this document.

5.2 ExtensionsExtension modules don’t generate source code. As such, source code for custom extensions is always available fordetachment and reuse. Just use Integration Studio, as usual, to open and compile the source code using VisualStudio.

5.3 OutSystems Scheduler ServiceIf you are using Timers or BPT Activities in your applications you will be able to keep this functionality even afterdetaching. Unlike other OutSystems services, the source code of the Scheduler Service will be provided for thispurpose. If you choose to re-implement these services using external tools you can later remove this dependencymanually.

5.4 Microsoft Excel FilesIf your application handles (reads or writes) data stored in MS Excel files, you will have to change theExcelTransaction() method (in the RuntimePlatform/ExcelTransaction.cs file) to use your own GemboxSpreadsheet license. In case of not having such a license, you can keep using the limited Gembox Spreadsheet freeedition. Alternatively you’ll find instructions in the source code file on how to replace this with a free MS Excel 32-bitimplementation.

5.5 Database ConfigurationYour application data will be preserved, either in the same databases/schemas and database server, or by movingthe databases/schemas from the current database server to a new one. To use a new database server you have tomanually reconfigure your database connection strings.

These can be found at C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG\machine.config, under theappSettings element.

To do this:

1. Locate the machine.config files for .NET Framework 2.0, on both the old and the new server. Open themwith a text editor;

a. On 64-bit machines you should update both the 32 and the 64-bit configuration files. These areusually available in the following locations:

i. %WINDIR%\Microsoft.NET\Framework\v2.0.50727\CONFIG\

ii. %WINDIR%\Microsoft.NET\Framework64\v2.0.50727\CONFIG\

2. Copy the appSettings tag from the machine.config file in the OutSystems Server to the same location in thenew server.

<appSettings>

…

</appSettings>


Note that actual tag contents may vary, and even include settings that are not related to the OutSystemsPlatform. As a rule of thumb we recommend that you copy only the entries (keys) with the“OutSystems.HubEdition” prefix.

3. Change the connection strings. You will not be able to use them encoded, so you need to convert them toplain text format:

user id=user; password=password; data source=database; initial catalog=catalog;

There are 4 connection strings to declare:

Connection user id catalog

SQLDBAdminConnectionString OSAdmin OutSystems

SQLDBConnectionString OSRuntime OutSystems

SQLDBLogConnectionString OSLog OutSystems

SQLSessionDBConnectionString OSState ASPState

5.6 Encrypted Configuration DataEncrypted configuration data must be reset to plaintext in order to work properly with the detached source code.This applies to system configuration data stored in system database and/or system files. Just locate and reset theencrypted configuration items located at these places:

· The <appSettings> element in the machine.config file

Update the connection string keys (check previous topic to learn how to locate and update this file)

· The OSSYS_PARAMETER table in the metadata database

Update the connection string entries

OutSystems Platform 8 - The Detach Process for .NET

Documents

Transcript of OutSystems Platform 8 - The Detach Process for .NET