.NET COMPONENT DEVELOPMENT GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2017 Copyright Notice ©2016 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval. Acknowledgments and References To print photographs or files of computational results (figures and/or data) obtained using BIOVIA software, acknowledge the source in an appropriate format. For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations were performed with the DMol3 program, and graphical displays generated with Pipeline Pilot." BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to [email protected], or in writing to: BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA Contents Chapter 1: Introduction 1 About .NET Component Development 1 Who Should Read this Guide 1 Requirements 1 Getting Started with .NET Component Development 1 .NET Component API 2 Component Interface 2 Additional Information 2 Chapter 2: .NET Integration Components and Examples 3 Dynamic .NET (on Server) Component 3 Dynamic C# (on Server) and Dynamic VB.NET (on Server) Components 3 Dynamic C# Example 3 .NET (on Server) Component 6 Packaging for the .NET (on Server) component 7 Activating the Package 7 .NET Example, Visual Studio 2008 7 .NET Example, Visual C# 2010 Express 8 Configuring the component in Pipeline Pilot Client 8 Debugging your assembly in Visual Studio 2008 9 Chapter 3: Key Interfaces 11 .NET Component API Reference 11 Appendix A: Running .NET Components without Internet Access 12 Chapter 1: Introduction About .NET Component Development The Integration collection includes tools for developing components using any language supported by the Microsoft .NET Framework, such as C# or VB.NET. Who Should Read this Guide This guide provides steps for creating a new component using the .NET API, including the necessary architectural background and technical instructions for creating, testing, and deploying your customized .NET components. Requirements In the development and deployment process, a given computer can play one or more of the following roles: Client, Server, and Development. Client Server Development Non- Pipeline Pipeline Pilot Microsoft Visual Studio: 2008, 2010, 2010 Express dynamic Pilot Client Server installation See: http://www.visualstudio.com/en- .NET installation .NET Framework US/products/visual-studio-express-vs runtime version Access to the server machine for uploading the 2.0 or later* developed assembly if the Development and Server machines are not one and the same. Dynamic Pipeline Pipeline Pilot Any development is done on the client machine .NET Pilot Client Server installation installation Note: If the server lacks an appropriate version of the *.NET Framework .NET Framework runtime, this error message is runtime version displayed: 2.0 or later "Failure to initialize the .NET Framework runtime. Please ensure the .NET Framework runtime [version_ number] is installed." Getting Started with .NET Component Development The tools available for developing components for the .NET platform include: Examples that demonstrate how to design .NET components that access the Pipeline Pilot data model to carry out a variety of tasks. See Chapter 2: .NET Integration Components and Examples. .NET-based components, which are listed in Chapter 2: .NET Integration Components and Examples. The .NET Component API reference in the Pipeline Pilot Help Center. Microsoft Visual Studio (or equivalent), including the .NET Framework and accompanying documentation. Introduction | Page 1 .NET Component API The .NET Component API provides a convenient way to access and modify the data structures, including the data records that flow through the components, the various parameter settings, and the global properties of the enclosing protocol. The API is implemented in an object-oriented fashion that reflects the natural syntax and features of the .NET programming languages. For the .NET API definition, see Microsoft's published API References for C# and VB.NET (or any other .NET language). Component Interface The IComponent interface, which resides in the com.scitegic.pilot namespace, allows your .NET components to be used in a protocol. Your .NET component must implement all three methods of the IComponent interface: OnInitialize: Executed once before processing the first data record. Even a component that receives no input will have this method called exactly one time. OnProcess: Executed for each data record passed as input or generated by the component. OnFinalize: Executed after processing the last data record. Note: This document assumes you are familiar with Component Lifetime Management, explained in the Protocol Development Quick Start Guide. Additional Information For more information about the Pipeline Pilot Integration collection and other BIOVIA software products, visit https://community.3dsbiovia.com. Page 2 | Pipeline Pilot • .NET Component Development Guide Chapter 2: .NET Integration Components and Examples The following components can be used for integrating third-party applications using a .NET solution: Dynamic .NET (on Server) Dynamic C# (on Server) and Dynamic VB.NET (on Server) .NET (on Server) Note: These components are currently only available on Windows and require that the server has Microsoft .NET Framework version 2.0 or later. Dynamic .NET (on Server) Component Dynamic .NET (on Server) allows for the dynamic execution of source code of any .NET language (such as C# and VB.NET), with the assumption that the appropriate .NET compiler is installed on the server. It performs an on-the-fly compilation of the source code, generating a binary assembly, which is passed internally to the .NET (on Server) component for execution. The main advantage of a dynamic component is its ease of use for setup and simple coding tasks, such as examples and rapid prototyping. A use case is integrating the existing functionality of an assembly into Pipeline Pilot. Additional Parameters: Parameter Description Source The source code to compile in the .NET language specified by the Language parameter. Language The .NET language of the source code, such as C# or VB. .NET Compiler 2.0 Version 3.0 3.5 4.0 Dynamic C# (on Server) and Dynamic VB.NET (on Server) Components Dynamic C# (on Server) and Dynamic VB.NET (on Server) are specialized versions of the Dynamic .NET (on Server) component that provide boilerplate code you can run as is, using default parameters. Note: The default code, which is specified by the Source parameter, is template code for your custom functionality. Dynamic C# Example The following example shows how to use the Dynamic C# (on Server) component. To create a protocol that uses a component written in C#: .NET Integration Components and Examples | Page 3 1. Open the Pipeline Pilot Client and create a new protocol. (It will match the Protocol named Hello World using Dynamic C#) 2. Add a Generate Empty Data component. If you change the C# component code to create data records, you do not need this component. 3. Add a Dynamic C# (on Server) component and connect it to the Pass port on Generate Empty Data. 4. Add a Data Record Tree Viewer component and connect it to the Pass port on Dynamic C# (on Server). 5. In the Dynamic C# (on Server) component, set the .NET Class parameter to HelloWorld. 6. Edit the Source parameter by pasting in the following code: using System; using com.scitegic.pilot; public class HelloWorld : IComponent { private String m_name; public State OnInitialize(IContext context) { // Retrieve component parameters. IPropertyCollection parameters = context.GetComponentParameters (); IProperty property = parameters.FindByName(@"Name"); // If the property 'Name' is specified, we will use its value, otherwise // we will just use a hard-coded string. if (property != null) m_name = property.GetValue().GetString(); else m_name = @"HelloWorld"; // Request to process any input data records. // Note: For information on choosing the right return value for the specific // component purpose, see the 'Protocol Development Quick Start Guide' // document, 'Component Lifetime Management' section. return State.ReadyForInputData; } public State OnProcess(IContext context, IDataRecord data) { // Create a property on the data record. INode node = data.GetRoot(); node.GetProperties().Define(@"Hello World").SetValue(@"From " + m_name); // Ready to process any additional input data records. // Note: For information on choosing the right return value for the specific // component purpose, see the 'Protocol Development Quick Start Page 4 | Pipeline Pilot • .NET Component Development Guide Guide' // document, 'Component Lifetime Management' section. return State.ReadyForInputData; } public void OnFinalize(IContext context) { // Nothing to do in this case. } } 7. Run the protocol. The result is: 8. To close the Data Record Tree Viewer dialog, click either Hide or Show Next. 9. Add a String parameter Name to the C# component: a. Right-click the C# component and select Edit. b. Click