summary

External libraries SDK README

The OutSystems External Libraries SDK allows you extend your ODC apps with custom C# code. The SDK supports modern .NET 8.0+ and integrates with your preferred IDE.

You decorate your C# code with SDK attributes that map directly to OutSystems visual language elements. This means you can expose your custom C# code as an ODC external library with reusable server actions and structures and use it across any ODC app. For detailed information, refer to Extend your apps with custom code.

For building your custom code, you can either start from scratch or accelerate development by using ready-made templates.

Once you build and package your external code, you can upload it to the ODC Portal and make it available as an external ODC library.

Prerequisites

.NET 8.0 SDK installed.
NuGet package manager installed.
An IDE that supports building .NET projects. For example, Visual Studio, Visual Studio Code, or Jet Brains Rider.
Basic knowledge of C# programming concepts.

Build external logic using SDK

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

Build external logic from scratch

To build external logic with C# using Microsoft Visual Studio 2022 with .NET 8.0, follow these steps:

From the Create a new project window select the Class Library template.
Give the project a name, for example ClassLibrary1. You must select .NET 8.0 (Long-term support) as the framework. Click Create.
From the Solution Explorer pane, right-click the project name and select Manage NuGet packages... Search for and install OutSystems.ExternalLibraries.SDK. If you want to enable logging in your C# code, install Microsoft.Extensions.Logging version 8.0.0. For tracing functionality, System.Diagnostics is part of the standard .NET library and is available by default.

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.

 using OutSystems.ExternalLibraries.SDK;

 namespace MyCompany
 {
     [OSInterface]
     public interface IMyLibrary
     {
         string SayHello(string name, string title);
         string SayGoodbye(string name);
     }
 }

Create a public class implementing that interface. Optionally for logging your code, use Microsoft Extension ILogger Interface. These logs can then be accessed from the ODC portal. You can also create custom spans/activities for distributed tracing by using the current activity source to monitor the performance and behavior of your external logic.

Here's an example of a class that uses Microsoft Extension ILogger Interface to log the code and creates custom spans for tracing.

    using Microsoft.Extensions.Logging;
    using System.Diagnostics;

    namespace MyCompany
    {
        public class MyLibrary : IMyLibrary
        {
            private readonly ILogger _logger;

            public MyLibrary(ILogger logger)
            {
                _logger = logger;
            }

            public string SayHello(string name, string title = "Mr./Ms.")
            {
                using var activity = Activity.Current?.Source.StartActivity("MyLibrary.SayHello");
                _logger.LogInformation($"Saying hello to {name} with title {title}");
                return $"Hello, {title} {name}";
            }

            public string SayGoodbye(string name)
            {
                using var activity = Activity.Current?.Source.StartActivity("MyLibrary.SayGoodbye");
                _logger.LogInformation($"Saying goodbye to {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.

You can expose a server action using external code with optional parameters by adding a default value to the parameter in the action definition. In the above example, the title parameter is optional and has a default value "Mr./Ms.".

Add tracing to your custom code

To create custom spans for distributed tracing in your external logic, use Activity.Current?.Source.StartActivity() to access the current activity source. This allows you to monitor the performance and behavior of your external logic operations within the ODC request trace.

When creating spans:

Use descriptive names that indicate the operation being performed (e.g., "Iban.Parse", "MyLibrary.SayHello")
Wrap the span creation in a using statement to ensure proper disposal
The span automatically becomes included in the distributed trace when your external logic is called from ODC apps

Here's an example based on the IBAN checker template:

    public Structures.Iban Parse(string value)
    {
        using var activity = Activity.Current?.Source.StartActivity("Iban.Parse");
        _logger.LogInformation("Parsing IBAN: {IbanValue}", value);
        return new Structures.Iban(_parser.Parse(value));
    }

This approach provides detailed tracing information that helps with monitoring and troubleshooting your external logic within the broader ODC application context.

For detailed information about errors, refer to External libraries SDK errors.

Once the code is successfully built, save the project and publish it.

To publish the code follow these steps:
1. Right-click {NAME_OF_SOLUTION} and click Open in Terminal.
2. Execute dotnet publish -c Release --no-self-contained
  
  The published code runs in a Linux container. If your library has runtime-specific dependencies then you should publish it specifying the runtime: dotnet publish -c Release linux-x64 --no-self-contained
Zip the contents of the publish output folder to the root of a ZIP file.
- For a cross-platform publish, the folder path is ./{NAME_OF_SOLUTION}/bin/Release/net8.0/publish/*.
- For a linux-x64 runtime-specific publish, the folder path is ./{NAME_OF_SOLUTION}/bin/Release/net8.0/linux-x64/publish/*.
Upload the ZIP file to the ODC Portal. For detailed information, refer to Extend your apps with custom code.

Once the external code is published and uploaded in ODC portal, you must create an external ODC library, publish, and release the library. For detailed information, refer to Upload and publish the external logic. Once the external library is released, you can consume the external logic across your ODC organization's apps and existing libraries.

For detailed information about best practices, refer to Best practices for using external libraries.

Build external logic using templates

You can also get started building external logic for your OutSystems apps by using ready-made templates. These templates leverage the OutSystems External Libraries SDK. You can choose from a basic or advanced template, both designed to help you implement custom C# code and expose it to your apps.

The basic template covers simple use case for checking the validity of your International Bank Account Number (IBAN), while the advanced template includes complex use cases for IBAN validation. You can download a template, open it in your IDE, and adapt the code to fit your requirements saving you time and effort as you extend your app’s capabilities.

Using basic IBAN checker template

Download and unzip the basic template file from the SDK GitHub repository.
Load the C# project file, OutSystems.IbanChecker.csproj, using a supported IDE.

The following files are available 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:
Edit the code to meet your use case. If your project requires unit tests, modify the examples found in ../OutSystems.IbanChecker.UnitTests/IbanCheckerTests.cs accordingly.
Run the Powershell script generate_upload_package.ps1 to generate ExternalLibrary.zip. Rename as required.

For detailed information about errors, refer to External libraries SDK errors.

Upload the generated ZIP file to the ODC Portal. For detailed information, refer to Extend your apps with custom code.

For detailed information about best practices, refer to Best practices for using external libraries.

Using advanced IBAN checker template

Download and unzip the advanced template file from the GitHub repository.
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.
Edit the code to meet your use case. If your project requires unit tests, modify the examples found in ../OutSystems.IbanChecker.UnitTests/IbanCheckerTests.cs accordingly.
Run the Powershell script generate_upload_package.ps1 to generate ExternalLibrary.zip. Rename as required.

For detailed information about errors, refer to External libraries SDK errors.

Upload the generated ZIP file to the ODC Portal. For detailed information, refer to Extend your apps with custom code.

For detailed information about best practices, refer to Best practices for using external libraries.

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) Description (Description) IconResourceName (Icon) OriginalName (Source name used for key calculation)
`[OSAction]`	Server action	Description (Description) IconResourceName (Icon) ReturnType (Output parameter type) ReturnName (Output parameter name) OriginalName (Source name used for key calculation)
`[OSParameter]`	Input/output parameter	DataType (DataType) Description (Description) OriginalName (Source name used for key calculation)
`[OSStructure]`	Structure	Description (Description) OriginalName ([Source Name used for the key calculation])
`[OSStructureField]`	Structure attribute	DataType (DataType) Description (Description) Length (Length) Decimals (Decimals) IsMandatory (IsMandatory) 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.

Troubleshooting

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

For detailed information about errors, refer to External libraries SDK errors.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

External libraries SDK README

Prerequisites

Build external logic using SDK

Build external logic from scratch

Add tracing to your custom code

Build external logic using templates

Using basic IBAN checker template

Using advanced IBAN checker template

Reference

Troubleshooting

Related resources

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

External libraries SDK README

Prerequisites

Build external logic using SDK

Build external logic from scratch

Add tracing to your custom code

Build external logic using templates

Using basic IBAN checker template

Using advanced IBAN checker template

Reference

Troubleshooting

Related resources