OutSystems.ExternalLibraries.SDK 1.3.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package OutSystems.ExternalLibraries.SDK --version 1.3.1
NuGet\Install-Package OutSystems.ExternalLibraries.SDK -Version 1.3.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OutSystems.ExternalLibraries.SDK" Version="1.3.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add OutSystems.ExternalLibraries.SDK --version 1.3.1
#r "nuget: OutSystems.ExternalLibraries.SDK, 1.3.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install OutSystems.ExternalLibraries.SDK as a Cake Addin
#addin nuget:?package=OutSystems.ExternalLibraries.SDK&version=1.3.1

// Install OutSystems.ExternalLibraries.SDK as a Cake Tool
#tool nuget:?package=OutSystems.ExternalLibraries.SDK&version=1.3.1

External Libraries SDK

ODC External Libraries SDK

Table of Contents

  1. Overview
  2. Prerequisites
  3. Usage
    1. From scratch
    2. From a template
  4. Reference
  5. Best Practices
  6. Troubleshooting
  7. License

1. Overview

This SDK is part of the OutSystems Developer Cloud (ODC) External Logic feature that you use to extend your apps built in the OutSystems visual language with custom code.

Use of this SDK is the first step in extending an ODC app. You use it to decorate the code of a C# .NET 6 project with SDK attributes that map to OutSystems visual language elements.

2. Prerequisites

  • .NET 6.0 SDK installed.
  • An IDE that supports building .NET 6 projects. For example, Visual Studio, Visual Studio Code, and Jet Brains Rider.
  • Basic knowledge of C# programming concepts.

3. Usage

You can start developing external logic for an ODC app from scratch or using one of the provided templates.

From scratch

Using Microsoft Visual Studio, for example:

  1. From the Create a new project window select the Class Library template.

  2. Give the project a name, for example ClassLibrary1. You must select .NET 6.0 (Long-term support) as the framework. Click Create.

  3. From the Solution Explorer pane, right-click on the project name and click Manage NuGet packages... Search for OutSystems.ExternalLibraries.SDK, select the result and click Install.

  4. Create a public interface containing the methods you want to expose as server actions to your ODC apps and libraries. Then decorate it with the OSInterface attribute. For example,

     using OutSystems.ExternalLibraries.SDK;
    
     namespace MyCompany
     {
         [OSInterface]
         public interface IMyLibrary
         {
             public string SayHello(string name);
             public string SayGoodbye(string name);
         }
     }
    
  5. Create a public class implementing that interface. For example,

     namespace MyCompany
     {
         public class MyLibrary : IMyLibrary
         {
             public string SayHello(string name) {
                 return $"Hello, {name}";
             }
    
             public string SayGoodbye(string name) {
                 return $"Goodbye, {name}";
             }
         }
     }
    

    The exposed methods can only have:

    • Basic .NET types: string, int, long, bool, byte[], decimal, float, double, DateTime.
    • Structs decorated with the OSStructure attribute.
    • Lists (any type inheriting from IEnumerable) of any of the previous two types.
  6. Once you are finished with the code, save the project and publish it. For example, right-click Solution ClassLibrary1 and click Open in Terminal. Run command dotnet publish -c Release.

  7. Zip the contents of publish output folder (normally this is, for example, ./ClassLibrary1/bin/Release/net6.0/publish/*) to the root folder of a ZIP file called, for example, ExternalLibrary.zip, the name of your external library.

    ℹī¸ The maximum supported size of the ZIP file in 40MB.

  8. Upload the ZIP file to the ODC Portal. See the External Logic feature documentation for guidance on how to do this.

From a template

IBAN (International Bank Account Number) checker: Basic version
  1. Download and unzip the basic template file from the SDK GitHub repository.

  2. Load the C# project file, OutSystems.IbanChecker.csproj, using a supported IDE.

    Files in the project:

    • IIbanChecker.cs: Defines a public interface named IIbanChecker, decorated with the OSInterface attribute. The interface has a single method named Parse, which takes an IBAN string value as input and returns an Iban struct. Parse is exposed as a server action to your ODC apps and libraries.

    • IbanChecker.cs: Defines a public class named IbanChecker that implements the IIbanChecker interface. The class is a convenient wrapper for the IbanNet library, an open-source library that provides functionality for parsing and validating IBANs. The class has a private field named _parser, which is an instance of the IIbanParser interface.

    • Iban.cs Defines a struct named Iban, decorated with the OSStructure attribute. The struct has four public properties: Country, Bban, BankIdentifier, and BranchIdentifier. Iban is exposed as a structure to your ODC apps and libraries.

    UML diagram:

    Basic UML diagram

  3. Edit the code to meet your use case.

  4. Run the Powershell script generate_upload_package.ps1 to generate ExternalLibrary.zip. Rename as required.

  5. Upload the generated ZIP file to the ODC Portal. See the External Logic feature documentation for guidance on how to do this.

IBAN (International Bank Account Number) checker: Advanced version
  1. Download and unzip the advanced template file from the GitHub repository.

  2. Load the C# project file, OutSystems.IbanChecker.csproj, using a supported IDE.

    Files in the project:

    • IIbanChecker.cs: Defines a public interface named IIbanChecker decorated with the OSInterface attribute. The interface has four methods:

      • Parse: Takes an IBAN string as input and returns an Iban struct.
      • TryParse: Attempts to parse an IBAN string as input and returns a boolean success indicator along with the parsed Iban struct.
      • Validate: Takes an IBAN string as input as checks it against a specific rule and a list of rejected countries.
      • Format: Takes an Iban struct and an optional format string as input and returns a formatted string representation of the IBAN.

      Each method is exposed as a server action to your ODC apps and libraries.

    • IbanChecker.cs: Defines a public class named IbanChecker that implements the IIbanChecker interface. The class is a convenient wrapper for the IbanNet library, an open-source library that provides functionality for parsing and validating IBANs. The class contains private fields _parser and _validator, which are instances of the IIbanParser and IIbanValidator interfaces. The constructor initializes these instances for use in the class methods.

    • Structures/Iban.cs Defines a struct named Iban, decorated with the OSStructure attribute. The struct has four public properties: Country, Bban, BankIdentifier, and BranchIdentifier. It's exposed as a structure to your ODC apps and libraries.

    • Structures/IbanCountry.cs Defines a struct named IbanCountry, decorated with the OSStructure attribute. The struct has five public properties: TwoLetterISORegionName, DisplayName, NativeName, EnglishName, and DomesticAccountNumberExample. It's exposed as a structure to your ODC apps and libraries.

    • Structures/ValidationResult.cs Defines a struct named ValidationResult, decorated with the OSStructure attribute. The struct has three public properties: AttemptedValue, Country, and Error. It's exposed as a structure to your ODC apps and libraries.

    • CustomRules/RejectedCountriesRule.cs: Defines a custom IBAN validation rule, RejectCountryRule, to reject specified country codes. It also defines an associated error result class, CountryNotAcceptedError, for handling rejected countries.

  3. Edit the code to meet your use case.

  4. Run the Powershell script generate_upload_package.ps1 to generate ExternalLibrary.zip. Rename as required.

  5. Upload the generated ZIP file to the ODC Portal. See the External Logic feature documentation for guidance on how to do this.

4. Reference

The table below maps the .NET attributes exposed by the SDK to the corresponding OutSystems elements. Click the link embedded link for further information.

.NET attribute OutSystems element .NET attribute property (OutSystems element property)
[OSInterface] External library Name (Name)<br>Description (Description)<br>IconResourceName (Icon)<br>OriginalName (Source name used for key calculation)
[OSAction] Server action Description (Description) <br>IconResourceName (Icon)<br>ReturnType (Output parameter type)<br>ReturnName (Output parameter name)<br>OriginalName (Source name used for key calculation)
[OSParameter] Input/output parameter <br>DataType (DataType)<br>Description (Description)<br>OriginalName (Source name used for key calculation)
[OSStructure] Structure <br>Description (Description)<br>OriginalName ([Source Name used for the key calculation])
[OSStructureField] Structure attribute <br>DataType (DataType)<br>Description (Description)<br>Length (Length)<br>Decimals (Decimals)<br>IsMandatory (IsMandatory)<br>OriginalName (Source name used for key calculation)
[OSIgnore] Use to decorate a public property/field within a .NET struct decorated with to specify that it shouldn't be exposed as an OutSystems Structure Attribute.

5. Best Practices

App architecture using external logic

The server actions you build in the OutSystems visual language execute directly in the ODC Runtime, the same infrastructure as the app.

Server actions your apps consume through external logic are slightly different in that they execute outside of this Runtime infrastructure. Each time your app calls a server action exposed by an external library, it makes an HTTPS call to an external service. This adds a small latency to the execution time of the server action. You should consider this when building an ODC app that uses external logic: is there any way to minimize the number of calls to the server action(s)?

6. Troubleshooting

Upload errors

All validation of your external logic is done when uploading the ZIP file to the Portal.

Use the error page documentation for guidance.

7. License

BSD-3 Clause

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • net6.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.4.0 156,896 6/19/2023
1.3.2 410 5/15/2023
1.3.1 204,030 4/18/2023
1.3.0 194 4/17/2023
1.1.0 3,837 4/13/2023