Getting Started With C# and .NET

Prerequisites

API applications should use .NET Core 3.1 or .NET 5 or later. See Troubleshooting .NET for help with installing .NET.

The API targets .NET Standard 2.0 so you can use it with .NET Framework 4.7.2 or later. .NET Framework is being phased out and we strongly recommend that you use .NET Core 3.1 or later if at all possible. Note that some earlier versions of .NET Framework will compile an API project but they won't work.

NuGet Package

The API is available as a NuGet package.

This can be added to your project in the usual way. If you are unfamiliar with using Nuget packages then this guide from Microsoft should help.

Examples

Please see the examples for example projects. We recommend that you download and run one of the examples before creating your own project.

The easiest way to do this is to checkout the whole samples project with:

git clone https://github.com/arup-group/oasys-api-samples.git

Here's the simplest possible example using the AdSec API:

using Oasys.AdSec;

class SimpleProgram {
    static void Main(string[] args) {
        System.Console.WriteLine("This AdSec API version is " + IVersion.Api());
    }
}

There are more examples available from the Oasys API Samples website.

Known Issues

BadImageFormat Exception

The .NET Core runtime throws a BadImageFormat exception if it's unable to load the API and all of its dependencies. e.g.

Unhandled exception. System.BadImageFormatException: Could not load file or assembly 'AdSec_API, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'.
An attempt was made to load a program with an incorrect format.
File name: 'AdSec_API, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'
   at Version.Program.Main(String[] args)

The usual reason is that one of the native DLLs that the API requires has been deleted from your project's output directory. A clean build should fix the problem.

As of 2021, .NET Core throws BadImageFormat for a very wide variety of reasons when it starts an application. For example, we've seen it happen if the API project is named "Version". In that renaming the project solved the issue.