Prerequisites

1. .Net Core SDK
2. .Net IDE of choice
3. Access to the SkySync SDK packages

Getting Started

All of our tutorials will begin from the command-line. This is the most portable way to work with the dotnet CLI and makes no assumptions about your operating system or IDE of choice. In order to make it super easy to create custom SkySync Platform extensions, we deliver a custom dotnet new template package. Your IDE should have details available on how to leverage custom dotnet new templates from within the IDE if you prefer to stay in there. If you are unfamiliar with custom templates within the dotnet CLI, you can review here and here for more information. Our first step is to install the SkySync dotnet new template package. 

dotnet new --install PortalArchitects.CustomExtension.Templates

If you are installing a beta version of the template, then you need to specifically include the version that you would like to install.

dotnet new --install PortalArchitects.CustomExtension.Templates::4.X.0-beta-100

If you have a previous version of the template, you will need to uninstall that version first. There are circumstances when the dotnet new command will not uninstall and in those, it will need to be reinitialized.

# uninstall the template
dotnet new --uninstall PortalArchitects.CustomExtension.Templates
# or reinitialize
dotnet new --debug:reinit

Creating Your First Extension

While there are a number of parameters that you can use to customize the project generated by the dotnet new template, the most basic extension can be created using:

dotnet new skysynclib --name MyCustomExtension

This will create two new projects within a "MyCustomExtension" directory. The first is the actual extension within src\MyCustomExtension\MyCustomExtension.csproj and the second is a pre-configured test project within test\MyCustomExtension.Tests\MyCustomExtension.Tests.csproj. Due to a limitation in the tooling, it does not currently create a new solution to go with these new projects. In order to work around that, it is recommended that you run the following:

cd MyCustomExtension
dotnet new solution
dotnet sln add src\MyCustomExtension\MyCustomExtension.csproj
dotnet sln add test\MyCustomExtension.Tests\MyCustomExtension.Tests.csproj

This will create a solution that contains the two new projects that we created in the previous step.

Developing our Extension

Build

To build your extension, you can run the following:

cd MyCustomExtension
dotnet build

This will build your extension in the Debug configuration as well as copy the extension into the appropriate directory on your machine for SkySync to pick it up if you have a local copy that you can use to test live within the product.

Test

It is recommended that as you are developing your extension that you create a suite of automated tests that can exercise the functionality of your extension. Depending on the type of extension that you are developing, SkySync has a number of test utilities that can be leveraged to assist in creating your automated tests. Those are discussed in other guides that dive deeper into the more specific types of extensions that SkySync supports. However, once you have written your automated tests then running is as simple as running the following:

cd MyCustomExtension\test\MyCustomExtension.Tests
dotnet test

If you intend to wire this up to run in your CI environment (i.e. TeamCity), then you will need to add --verbosity=normal to the above in order to get the build agent to report test progress correctly.

Deployment

Once your extension is fully developed, then you are ready to package the extension for deployment. This can be accomplished by running the following on your extension project.

cd MyCustomExtension\src\MyCustomExtension
dotnet pack --configuration Release

This will package up the extension into a NuGet package (.nupkg file) that can be deployed to a SkySync instance. The package will be located at MyCustomExtension\src\MyCustomExtension\bin\Release\MyCustomExtension.nupkg.