Hello World API

This tutorial will show how to create a myAvatar ScriptLink-compatible API with .NET 8.0.

Before You Begin

You will need the following to complete this tutorial:

• Visual Studio 2022 or Visual Studio Code
• .NET SDK

Visual Studio

When using Visual Studio you will want the following workloads and components installed.

• ASP.NET and web development workload.
• .NET 8.0 Runtime (if not already included with the install of the above workload)

Visual Studio Code

The following extensions are recommended when using Visual Studio Code.

• C# Dev Kit
• REST Client

Create Project

Visual Studio

1. Launch Visual Studio 2022.
2. Create a new project.
3. Select C# and then search for ASP.NET.
4. Select ASP.NET Core Empty and then select Next.
5. Configure your new project.
   1. Set your project name.
   2. Select the location to store your project.
   3. Set your solution name.
   4. Don't check Place solution and project in the same folder. we will be adding additional projects to this solution in other tutorials.
6. Select Next.
7. Set the Framework to .NET 8.0 (Long Term Support).
8. Select Configure for HTTPS.
9. Select Create.

Visual Studio Code

1. Open Windows Terminal.
2. Navigate to the directory you wish to store the solution and project in.
3. Create the solution and then change to that directory

dotnet new sln --output ScriptLinkHelloWorldDemo
cd ScriptLinkHelloWorldDemo
dotnet new web --output ScriptLinkHelloWorldDemo
dotnet sln add ScriptLinkHelloWorldDemo/ScriptLinkHelloWorldDemo.csproj
code .

Add Dependencies

We will add two NuGet packages to our project.

• RarelySimple.AvatarScriptLink
• SoapCore

Visual Studio

1. Right-click on the soution in Solution Explorer and select Manage NuGet Packages for Solution....
2. Select Browse and search for AvatarScriptLink. Select RarelySimple.AvatarScriptLink by Scott Olson Jr and install this in your project.
3. Select Browse and search for SoapCore. Select SoapCore by Digital Design and install this in your project.
4. Select the Install tab, clear the search text and confirm you now have two packages installed in your project.

Visual Studio Code

1. Change to the project directory.
2. Select View > Terminal (Ctrl +`) to show the Terminal.
3. Install RarelySimple.AvatarScriptLink with dotnet add package RarelySimple.AvatarScriptLink.
4. Install SoapCore with dotnet add package SoapCore.

cd ScriptLinkHelloWorldDemo
dotnet add package RarelySimple.AvatarScriptLink
dotnet add package SoapCore

Create the Service Contract

1. Add a new class to your project named IScriptLinkService2015.
2. Implement the GetVersion and RunScript operation contracts as shown below.

/IScriptLinkService2015.cs

using RarelySimple.AvatarScriptLink.Objects;
using System.ServiceModel;

namespace ScriptLinkHelloWorldDemo
{
    [ServiceContract]
    public interface IScriptLinkService
    {
        [OperationContract]
        string GetVersion();

        [OperationContract]
        OptionObject RunScript(OptionObject optionObject, string parameter);
    }
}

Create ScriptLink Service

1. Add a new class to your project named ScriptLinkService.
2. Inherit this class from IScriptLinkService2015.
3. Implement the GetVersion and RunScript methods as shown below.

/ScriptLinkService.cs

using RarelySimple.AvatarScriptLink.Objects;

namespace ScriptLinkHelloWorldDemo
{
    public class ScriptLinkService : IScriptLinkService2015
    {
        public string GetVersion()
        {
            return "0.1.0";
        }

        public OptionObject2015 RunScript(OptionObject2015 optionObject, string parameter)
        {
            return optionObject.ToReturnOptionObject(ErrorCode.Alert, "Hello World!");
        }
    }
}

Update Program.cs

In this step, we are going to replace the default "Hello World!" API with our new ScriptLink-compatible API.

1. Open the Program.cs file.
2. Update the file to include the following:

/Program.cs

using Microsoft.Extensions.DependencyInjection.Extensions;
using SoapCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSoapCore();
builder.Services.TryAddSingleton<IScriptLinkService2015, ScriptLinkService>();
var app = builder.Build();

app.UseHttpsRedirection();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
    _ = endpoints.UseSoapEndpoint<IScriptLinkService>("/ScriptLinkService.asmx", new SoapEncoderOptions(), SoapSerializer.XmlSerializer);
    // Optional Alternative
    // _ = endpoints.UseSoapEndpoint<IScriptLinkService>("/ScriptLinkService.svc", new SoapEncoderOptions(), SoapSerializer.DataContractSerializer);
});

app.Run();

Update Launch Settings

This will help us launch the app and load the WSDL in the browser once running.

1. Expand the Properties Folder and open the launchSettings.json file.
2. In the https profile insert the following line before the applicationUrl: "launchUrl": "ScriptLinkService.asmx",.

Properties/launchSettings.json

{
    // previous content
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "ScriptLinkService.asmx",
      "applicationUrl": "https://localhost:7140;http://localhost:5106",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    // following content
}

Run the application

Visual Studio

1. Run/debug the application with the https profile.

Visual Studio Code

dotnet run --launch-profile https

Congratulations! You should now see your WSDL showing in the browser and are ready to make the API calls.

If the WSDL was not automatically launched in your browser, you can get the URL from the launchSettings.json file. For example, https://localhost:7140/ScriptLinkService.asmx as seen in the same launchSettings file above.