Extending Logic with C# Code

Extending Logic with C# Code:
Using a NuGet Package

OutSystems Inc. 5
901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 1

Table of Contents
Table of Contents 2
Define the Action in Integration Studio 4
Implement Action in Microsoft Visual Studio 9
Publish Extension and Sample App to OutSystems Server 13
Extend Sample App to Use Extension 17
Test Extension using Sample Application 21
End of Lab 25

OutSystems Inc. 5

Introduction
The power of the OutSystems platform comes from the combination of rapid development and
change using the visual low-code paradigm and the uncompromising capability to integrate and
be extended with other technologies.
Probably the best example of this is the capability to develop specific functionalities in the .NET
C# language. This is beneficial when the need to integrate with a legacy external system arises
or when we must invoke a specialized third-party executable.
In this lab we will be implementing an Action in C#, using OutSystems Integration Studio and
Microsoft Visual Studio, that will then be seamlessly callable from Service Studio modules, just
as any other Server Action would be.
The following sections will cover these scenarios:
● Create a C# Action with simple type parameters

● Use Visual Studio’s NuGet Package Manager to import a public .NET assembly into your
extension
● Publish Extension and use its functionality from a (sample) application
OutSystems Inc. 5

Define the Action in Integration Studio
We will start by creating an extension in Integration Studio containing a single Action that
requires no specialized types for its parameters. This action will allow the conversion of
Markdown1 text to HTML, which could be used to build a CMS2 in OutSystems.
To implement this we will be using both OutSystems Development Environment components

(Integration Studio and S
ervice Studio) and M
icrosoft Visual Studio. Please refer to an
earlier Lab if you don’t have these installed and configured yet.
1) Open Integration Studio and login in your OutSystems server (likely your personal
environment).
a) Launch I ntegration Studio f rom a Desktop shortcut or the Windows Start Menu
or
b) Connect Integration Studio to your OutSystems server using the icon on the top
toolbar

c) In the Connect to Environment dialog, enter the environment address,
username and password you will be using to carry out the exercises, and click
1
https://en.wikipedia.org/wiki/Markdown
2
https://en.wikipedia.org/wiki/Content_management_system

OutSystems Inc. 5

Connect.
NOTE: This login information is exactly the same as you use to connect Service
Studio to the OutSystems platform server.
2) Create a New Extension and name it “MarkdownToHTML”
a) In the top toolbar, click the N

ew button

b) Integration Studio will change to display a newly created extension, change its
name from the default “ Extension” to MarkdownToHTML and press Return

3) Define an Action named Markdown_ConvertToHTML, with a Text input and a Text

output parameter
OutSystems Inc. 5

a) Right-click the A
ctions folder and select A
dd Action.
b) In the new opened tab, type in M

arkdown_ConvertToHTML to change the Name o
f
the Action from the default “Action1”. Press Return
c) In the Parameters panel below, type in M

arkdown for the Name o
f the first
parameter. Leave it as an I nput Parameter, M
andatory and of Data Type
“Text”.
d) Below the M
arkdown parameter, type in H
TML for the Name o
f the second
parameter. Change its kind to Output Parameter by clicking on its icon. Leave its
Data Type as “Text”.
NOTE: Unticking the “Mandatory” c heckbox will allow an Input Parameter to be
made optional. The mandatory concept is not applicable to Output Parameters so
the checkbox in these parameters is non functional.
OutSystems Inc. 5

e) The Extension and Action definition should look like this
4) Generate the solution project skeleton and launch Visual Studio
a) In the top toolbar, press the Edit Source Code .NET b

utton

b) Integration Studio will automatically generate the C# source to match our
Extension definitions...
OutSystems Inc. 5

c) … and Microsoft Visual Studio will launch and load in the MarkdownToHTML
project, ready for editing

OutSystems Inc. 5

Implement Action in Microsoft Visual Studio

In this section we will flesh out the body of M
ssMarkdown_ConvertToHTML, to convert the
input Markdown to the desired HTML format, in C#.
Since Markdown conversion is not provided by the core Microsoft .NET Framework, we will be
using an external assembly to have access to this functionality, which we will import into the
extension using Microsoft’s NuGet Package Manager3.
In the interest of understandability, this is a very short example using only one external
dependency and a single line of C# code. Other exercise labs will employ more C# code, but will
remain of reduced size.
This is purely to simplify learning: there is (virtually) no constraints on the size and complexity of
the C# code you can develop inside an extension, or the libraries that can be pulled into these
extension projects.

1) Locate and understand the context of the Markdown_ConvertToHTML action in the C#
project
a) Double-click the MarkdownToHTML.cs file inside the MarkdownToHTML project in
the Solution Explorer to reveal the project’s main C# class
NOTE: Upon opening a source C# file, you may be notified that the file has
inconsistent line endings. This is not a problem so, on that dialog, simply leave
the Line ending to the suggested “Windows (CR LF)”, untick the “Always show this
dialog” and click Yes.
3
https://docs.microsoft.com/en-us/nuget/what-is-nuget

OutSystems Inc. 5

b) Notice the function MssMarkdown_ConvertToHTML, with parameters

ssMarkdown and s sHTML, where we will implement the “body” of our Action
NOTE: The Solution, Project and “main” C# source filename will always match the
name given to the Extension.
The C# function that implements Action <ACTION_NAME> is always named

Mss<ACTION_NAME>, while all parameters in the generated C# stub will be
named s s<PARAM_NAME>.
2) Import the CommonMark4 assembly into the extension project, using NuGet
a) Right-click the M
arkdownToHTML element in Solution Explorer tree, and select
the Manage NuGet Packages… option

b) On the main window, a NuGet management tab for the solution will appear.
Select the Browse tab and type in CommonMark in the search input

d) Locate and select CommonMark.NET from the result list on the left. The right
panel will show details about this assembly. Ensure the “0.15.1” version is
selected and press Install.
4
https://github.com/Knagis/CommonMark.NET#commonmarknet

OutSystems Inc. 5

NOTE: Later stable v

ersions of the assembly will likely work too, but were not
tested at the time this exercise was developed.
e) After acknowledging that this operation will make changes to your solution, the
Output Window will show the steps of the assembly installation.
f) Upon completion, expand the R
eferences node in the Solution Explorer panel:
CommonMark should be visible there. Select it and ensure its C
opy Local
property is set to “True”.

NOTE: Due to the way Integration Studio packs extensions, any external
assemblies or resources that are required for the extension to function will need
to reside inside the extension folder, on the appropriate subdirectory. The C
opy
Local property ensures this (i.e. that C
ommonMark.dll is inside the bin/ folder).
3) Implement the C# code for Markdown_ConvertToHTML

a) Open M
arkdownToHTML.cs by double-clicking the file in Solution Explorer, if
it’s not already showing in Visual Studio’s main editor
OutSystems Inc. 5

b) Move to the M
ssMarkdown_ConvertToHTML function definition

a) Replace the body of the function (i.e. between { and }) with the following C# code
// Convert markdown input into HTML output parameter

ssHTML = CommonMark.CommonMarkConverter.Convert(ssMarkdown);
c) Your function should now look like this
NOTE: We are simply calling the Convert() method of the class

CommonMarkConverter, included in the C
ommonMark namespace on our
action input parameter. We are then setting the output parameter to the result of
the conversion.
e) Ensure your extension has no errors by selecting the B

uild Solution option inside
the Build top menu option

f) The output window should show no errors

g) Close Microsoft Visual Studio using menu File, option Exit.
NOTE: Building the solution inside Visual Studio i s not strictly needed, as the
code will be rebuilt inside Integration Studio. We do so simply to speed up error
detection before leaving the Microsoft IDE.

OutSystems Inc. 5

Publish Extension and Sample App to OutSystems Server

In this section, we will publish the extension to the OutSystems server, making its functionality
available to be used by any of the OutSystems applications on that environment.
To simplify the testing of the MarkdownToHTML extension, a sample application (Micro CMS)
that can easily be expanded to accommodate the extension’s new features is provided. This
sample application will need to be published to your environment as well.
1) Add Microsoft N
uGet package information to Extension
a) Back in Integration Studio, click the Resources t ab, to switch the tree to
Extension contents display

NOTE: This view shows the filesystem tree based on where the Extension was
expanded in the developer’s machine. Files displayed comprise both included
(dark) and excluded (greyed-out) from the Extension package.
By default, Integration Studio already selects for inclusion file types it knows are
important for the functioning and future developments of the Extension (such as
.dll and .cs files). In this case we decided to override the default (of ignore) for
packages.config. We do this so Microsoft Visual Studio can keep track of the
CommonMark version we are currently using in the project.
b) Locate the packages.config file in the tree, right-click it and select I nclude in
Extension
OutSystems Inc. 5

2) Publish the MarkdownToHTML extension to the OutSystems server

a) Click the 1-Click Publish button on the top toolbar

b) Integration Studio should detect the inclusion of C
ommonMark into the project
and add the necessary resources to the Extension. It will then compile it and
publish it to the server.

NOTE: During the process, your extension will also be saved locally to your hard
drive. If you haven’t explicitly saved it before, you may be prompted for a path
halfway through this publication.

3) Publish the sample M
icro_CMS a
pplication into your server
a) Open Service Studio from the Start Menu or by double clicking the icon.
OutSystems Inc. 5

b) In the Connect to Environment or Switch Environment dialog, enter the

environment address, username and password you have been using for
Integration Studio, and click C
onnect.

c) In the Environment t op menu, select O
pen Files...

d) Change the the bottom-right file type Combo filter to show “ OutSystems
Application Pack (*.oap)”. Navigate to and select the M
icro CMS.oap s ample
application, and then press Open.
OutSystems Inc. 5

e) After confirmation, the Micro CMS a

pplication should install on your server
NOTE: After the installation completes, the application will be moved further
down in the list to be sorted alphabetically. Depending on how many applications
you have already installed, it may therefore move out of view (you can use search
to find it).

OutSystems Inc. 5

Extend Sample App to Use Extension

The sample M icro CMS a pplication is already functional, as it allows the user to create new
Content pages, list and view them. However, when creating content, if you want to add any
formatting, you will need to type in HTML tags yourself.
In this section we will change this application so that the content creator can use the much
more convenient markdown syntax to produce web pages.
1) Extend Micro CMS to be able to invoke the action M
arkdown_ConvertToHTML from
the M
arkdownToHTML Extension
a) Click the Micro CMS application from the list in S
ervice Studio to open it

b) Click the MicroCMS module inside the Micro CMS application view to open it

c) Click the Manage Dependencies i con on the top toolbar

d) In the Manage Dependencies d ialog, type in “ markdown” in the Producers filter
to narrow down the list. Then select the MarkdownToHTML E xtension on the
OutSystems Inc. 5

producer panel, followed by ticking the M arkdown_ConvertToHTML action in

the elements panel. Finally press O
K to close this dialog.
NOTE: Like any public action in Service Studio modules, C# actions created in an
extension and consumed from the dependencies dialog become - in practical
terms - indistinguishable from every other action in our (consuming) module.
2) Add the M
arkdown_ConvertToHTML functionality to the CMSEntryDetail s creen
a) In the Interface tab, double-click the O

nContentEditableChange screen action
(inside the CMSEntryDetail s creen) to open it in the canvas.
OutSystems Inc. 5

b) Drag a Run Server Action from the toolbox and drop it on the Action flow just
before the “ Save Edited Content” Assign statement.
c) On the S
elect Action p
opup, type in ”markdown” in the filter area, and
double-click the M
arkdown_ConvertToHTML action, to select it
d) Set the Markdown parameter of the M

arkdown_ConvertToHTML action call to
CMSEntryForm.Record.CMS_Entry.ContentEditable
OutSystems Inc. 5

e) Click on the “ Save Edited Content” Assign s tatement below, and change the
expression-side of the assignment to “Markdown_ConvertToHTML.HTML”
NOTE: The steps above are sufficient to use the extension functionality previously
implemented. However, if you press the S
ave button too rapidly after typing
things into the Content multi-line input, the latest changes may not be saved.
With this in mind, you may want to carry the following (multiple) step
f) Repeat steps a) to e) above, but this time inside the S

ave screen action (also
inside the CMSEntryDetail s creen)

OutSystems Inc. 5

Test Extension using Sample Application

It’s now time to try the improved MicroCMS a
pplication, that will now allow the input of
markdown for the creation / editing of new content.
1) Publish the MicroCMS m
odule and see the application in the browser.
a) Click the 1-Click Publish button to publish the module to the server.
b) After it’s done, press the Open in Browser button to open your application in
your default browser.
NOTE: If you are not yet logged into any application on your environment, you
will be taken to the login screen. Simply login with any Registered user and you’ll
be able to enter the application.
c) Your application should look something like this
2) Add a new content using Markdown and view it in a dedicated page
a) Press the “Create a new CMS Entry” link at the top-right corner of the application

OutSystems Inc. 5

b) In the New CME Entry screen, set the entry Title t o “Sample” and set the entry
Content to
Heading
=======
## Sub-heading
Paragraphs are separated

by a blank line.
Two spaces at the end of a line

produces a line break.
Text attributes _italic_,

**bold**, `monospace`.
Horizontal rule:
---
Bullet list:
* apples
* oranges
* pears
Numbered list:
1. wash
2. rinse
3. repeat
A [link][example].
[example]: http://www.outsystems.com
![Image](https://foundation.outsystems.net/resource/get/neo-mascot.pn
g "NEO")
OutSystems Inc. 5

c) When you stop typing, the right Preview panel will flash to show the HTML
version of the markdown content above. You should see something like this

d) Press the “Save” button to go back to the CMS Entries screen. Press the “Eye” icon
on the line of the Sample we just created
OutSystems Inc. 5

e) This will open a dedicated page to display just your HTML content!

OutSystems Inc. 5

End of Lab
In this exercise lab, we created an Extension module that adds new functionality to be used by
regular OutSystems Service Studio modules: adding a converter from Markdown to HTML.
We used Integration Studio to define an action prototype, and then Microsoft Visual Studio to
first import an external assembly into our C# project and then flesh out the action’s code.
We published the extension, as well as a starter sample CMS application.
We then extended that application to call the action from our Extension, and use the converter
every time we create new content in the CMS application, thus showing the seamless
integration of .NET C# into the OutSystems platform.
OutSystems Inc. 5

Extending Logic with C# Code

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Extending Logic with C# Code

Uploaded by

Copyright:

Available Formats

Define the Action in Integration Studio 4

Implement Action in Microsoft Visual Studio 9

Publish Extension and Sample App to OutSystems Server 13

Extend Sample App to Use Extension 17

Test Extension using Sample Application 21

End of Lab 25

The following sections will cover these scenarios:

● Create a C# Action with simple type parameters

Define the Action in Integration Studio

To implement this we will be using both OutSystems Development Environment components

2) Create a ​New Extension​ and name it ​“MarkdownToHTML”

a) In the top toolbar, click the N

3) Define an Action named ​Markdown_ConvertToHTML​, with a Text input and a Text

b) In the new opened tab, type in M

c) In the ​Parameters​ panel below, type in M

e) The Extension and Action definition should look like this

4) Generate the solution project skeleton and launch Visual Studio

a) In the top toolbar, press the ​Edit Source Code .NET b

Implement Action in Microsoft Visual Studio

b) Notice the function ​MssMarkdown_ConvertToHTML​, with parameters

The C# function that implements Action <ACTION_NAME> is always named

NOTE:​ Later ​stable v

3) Implement the C# code for Markdown_ConvertToHTML

// Convert markdown input into HTML output parameter

NOTE:​ We are simply calling the ​Convert()​ method of the class

e) Ensure your extension has no errors by selecting the B

Publish Extension and Sample App to OutSystems Server

2) Publish the ​MarkdownToHTML​ extension to the OutSystems server

b) In the ​Connect to Environment​ or ​Switch Environment ​dialog, enter the

e) After confirmation, the ​Micro CMS a

Extend Sample App to Use Extension

producer panel, followed by ticking the M ​ arkdown_ConvertToHTML​ action in

a) In the Interface tab, double-click the O

d) Set the ​Markdown​ parameter of the M

f) Repeat steps a) to e) above, but this time inside the S

Test Extension using Sample Application

c) Your application should look something like this

2) Add a new content using Markdown and view it in a dedicated page

Paragraphs are separated

Two spaces at the end of a line

Text attributes _italic_,

We published the extension, as well as a starter sample CMS application.

You might also like

2) Create a New Extension and name it “MarkdownToHTML”

3) Define an Action named Markdown_ConvertToHTML, with a Text input and a Text

c) In the Parameters panel below, type in M

a) In the top toolbar, press the Edit Source Code .NET b

b) Notice the function MssMarkdown_ConvertToHTML, with parameters

NOTE: Later stable v

NOTE: We are simply calling the Convert() method of the class

2) Publish the MarkdownToHTML extension to the OutSystems server

b) In the Connect to Environment or Switch Environment dialog, enter the

e) After confirmation, the Micro CMS a

producer panel, followed by ticking the M arkdown_ConvertToHTML action in

d) Set the Markdown parameter of the M