ASP.NET Application Development User Guide Edition 17.0 01 July 2014 Portrait Foundation ASP.NET Application Development User G u i d e ©2014 Copyright Portrait Software International Limited All rights reserved. This document may contain confidential and proprietary information belonging to Portrait Software plc and/or its subsidiaries and associated companies. Portrait Software, the Portrait Software logo, Portrait, Portrait Software's Portrait brand and Million Handshakes are the trademarks of Portrait Software International Limited and may not be used or exploited in any way without the prior express written authorization of Portrait Software International Limited. Acknowledgement of trademarks Other product names, company names, marks, logos and symbols referenced herein may be the trademarks or registered trademarks of their registered owners. About Portrait Software Portrait Software is now part of Pitney Bowes Software Inc. Portrait Software enables organizations to engage with each of their customers as individuals, resulting in improved customer profitability, increased retention, reduced risk, and outstanding customer experiences. This is achieved through a suite of innovative, insight-driven applications which empower organizations to create enduring one-to-one relationships with their customers. Portrait Software was acquired in July 2010 by Pitney Bowes to build on the broad range of capabilities at Pitney Bowes Software for helping organizations acquire, serve and grow their customer relationships more effectively. The Portrait Customer Interaction Suite combines world leading customer analytics, powerful inbound and outbound campaign management, and best-in-class business process integration to deliver real-time customer interactions that communicate precisely the right message through the right channel, at the right time. Our 300 + customers include industry-leading organizations in customer-intensive sectors. They include 3, AAA, Bank of Tokyo Mitsubishi, Dell, Fiserv Bank Solutions, Lloyds Banking Group, Merrill Lynch, Nationwide Building Society, RACQ, RAC WA, Telenor, Tesco Bank, T-Mobile, Tryg and US Bank. Pitney Bowes Software Inc. is a division of Pitney Bowes Inc. (NYSE: PBI). For more information please visit: http://www.pitneybowes.co.uk/software/ UK America Norway Portrait Software Portrait Software Portrait Software The Smith Centre 125 Summer Street Portrait Million Handshakes AS The Fairmile 16th Floor Maridalsveien. 87 Henley-on-Thames Boston, MA 02110 0461 Oslo Oxfordshire, RG9 6AB, UK USA Norway Email: [email protected] Email: [email protected] Email: [email protected] Tel: +44 (0)1491 416778 Tel: +1 617 457 5200 Tel: +47 22 38 91 00 Fax: +44 (0)1491 416601 Fax: +1 617 457 5299 Fax: +47 23 40 94 99 Edition 17.0 About this document Purpose of document This document provides guidelines for the usage of the Portrait Foundation Software Development Kit (SDK) in relation to ASP.NET application development. For a detailed overview of the SDK along with installation instructions please refer to the Software Development Kit User Guide. Intended audience Portrait Foundation project implementation teams. Related documents Software Development Kit User Guide (Foundation SDK User Guide) Enhancing ASP.NET Applications User Guide Localizing ASP.NET Applications User Guide Software release Portrait Foundation 5.0 or later. Portrait Foundation ASP.NET Application Development User Guide 3 of 40 Edition 17.0 Contents 1 Foundation Application Framework 6 2 Portrait Foundation application development concepts 7 2.1 Foundation application 7 2.2 Foundation package 7 2.3 Foundation implementation reference 7 2.4 Foundation custom control 9 2.5 Foundation data source controls 11 3 Foundation Web SDK 12 3.1 Web application framework 12 3.2 Creating a new web application 12 3.3 Creating a new web package 13 3.4 Creating new web pages 14 3.5 Using the web control library 25 3.6 Creating a new web control 32 3.7 Using a native ASP.NET Web Application Project 33 3.8 Error handling and reporting (Service Centre channel) 33 Appendix A AIT.Portrait.Web controls 37 Portrait Foundation ASP.NET Application Development User Guide 5 of 40 Edition 17.0 1 Foundation Application Framework The Portrait Foundation application framework is based on the standard Microsoft .NET framework and is represented by a set of interface definitions and base class implementations that bridge the technology specific application with the Portrait Foundation system. This framework manages the common functionality at the Portrait Foundation presentation layer and offers a high level interface for producing new or customised Portrait Foundation applications based on the .NET technology. Its source code cannot be modified by project implementations. Error handling and reporting functionality is provided in this framework, enabling applications to recover from transient errors and be more resilient. The error reporting framework allows easy diagnosis of system problems in a production environment. The Portrait Foundation application framework components are located in the following directory: <SDK_installation_directory>\Development Environment\dotNET\Portrait Framework Table 1 – Application framework assemblies Name Assembly Brief description Portrait elements AIT.Portrait.Web.dll Portrait web application applicable to the framework and the .NET Web forms Portrait web controls implementations library Portrait elements AIT.Portrait.dll Base classes for applicable to the integration with intrinsic .NET SDK Portrait functionality e.g. interop, logging, error handling. NB: All assemblies included in this framework are strong-named and reliant upon the specific public key. Portrait Foundation ASP.NET Application Development User Guide 6 of 40 Edition 17.0 2 Portrait Foundation application development concepts This section explains the key concepts involved in implementing a Portrait Foundation application. 2.1 Foundation application A Portrait Foundation application delivers a navigationally controlled and functionally rich environment using Microsoft ASP.NET. These applications typically correspond to an Application Framework Model (AFM) configured using the Portrait Foundation Configuration Suite. The starting point of any such application will be a request to run the AFM on the Process Server, which then controls the rest of application navigation. A Portrait Foundation application typically makes use of multiple portrait packages to deliver the functionality. 2.2 Foundation package A Portrait Foundation package contains the user interface collateral required to support a configured Package. This includes the implementation for the following configurable business entities: Implementation references for screens and custom views Data transformations for custom controls Input definitions for custom controls A Portrait Foundation package would typically reside in a package repository, along with the configuration collateral. 2.3 Foundation implementation reference A Portrait Foundation implementation reference corresponds to a configured Custom UI, Generated UI or View. The custom interaction sampled below has its implementation reference configured as AIT_HRZ_SearchForParty.aspx, therefore the web package should contain a web page with the same name to achieve the required business functionality at runtime. Portrait Foundation ASP.NET Application Development User Guide 7 of 40 Edition 17.0 Figure 1 – Configuration Suite Custom UI The view sampled below has its implementation reference configured as AIT_HRZ_WorkflowSummary.aspx, therefore the Web package should contain a Web page with the same name to achieve the required business functionality at runtime. Figure 2 – Configuration Suite View Portrait Foundation ASP.NET Application Development User Guide 8 of 40 Edition 17.0 2.4 Foundation custom control A Portrait Foundation custom control derives from a standard .NET WebControl and, in addition, implements the ICustomControl interface which allows the binding of the control to a configured custom control. The ICustomControl interface definition is specific to the technology being used and the details can be found in the technology specific sections. Listed below are the typical steps that are involved in the process of binding a Portrait Foundation custom control to a configured custom control: Request name binding Input interface definition Data transformation The sample below shows a custom control configured using the Portrait Foundation Configuration Suite: Figure 3 – Configuration Suite Custom Control ist break 2.4.1.1 Request name binding Every Portrait Foundation Custom control that can be dragged and dropped on a Portrait Foundation screen or view implements the RequestName property of the ICustomControl interface. The value of this property must be set to the name of the configured business custom control e.g. RequestName = SearchResults This property can be set in the design view by selecting the .NET control’s properties window. This tells the Portrait Foundation application framework that the .NET custom control sources its data from a configured custom control. Portrait Foundation ASP.NET Application Development User Guide 9 of 40 Edition 17.0 2.4.1.2 Input interface definition For every binding, a new entry needs to be added in the application/package custom control input definitions XML file, which usually resides in the xml subfolder. These definitions imply static data bindings for the configured