Development with Visual Studio Code

2020-08-16T06:39:47Z

Vula: /* Setting Up Project */

This tutorial explains a basic to develop & debug a RAGE-MP resource / server-side script using [[wikipedia:Visual_Studio_Code|VSCode]] on C# bridge

Note: it is not required for you to compile the .cs scripts to run the resource, you can let the server compile them when server starts.
[[#Client-side|See the comparison below]].

This tutorial will mainly describe about compiling your server-side resource into <tt>.dll</tt> binary which you can attach a debugger on it. A similar step can be also done in [[wikipedia:Visual Studio|Visual Studio IDE]], except the launch & task part.

== Requirement ==
* Visual Studio Code - [https://code.visualstudio.com/download Download]
* .NET Core SDK version 2.2 - [https://dotnet.microsoft.com/download/dotnet-core/2.2 Download] (As of RAGE:MP 0.3.7, Server side uses version 2.0.3 and Client side uses version 2.2.0 so it's safe to install the latest which are backward compatible)
* C# Extension for Visual Studio Code powered by OmniSharp - [https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp Download (in Visual Studio Code)]

== Setting Up Project ==
# Open Visual Studio Code on '''bridge/resources''' folder
# Create a new folder, example '''mygamemode''' then select the folder
# Open the terminal <kbd>'''Ctrl'''</kbd>+<kbd>'''`'''</kbd> (control + tilde)
# Enter <tt>></tt><code>dotnet new classlib -f netcoreapp2</code> to create a new .NET Core class library
# A <tt>.csproj</tt> file will be created, click to edit it
## [https://docs.microsoft.com/en-us/dotnet/standard/frameworks#how-to-specify-target-frameworks Change the TargetFramework] to <code>netcoreapp2.0</code>
## [https://docs.microsoft.com/en-us/dotnet/core/versions/selection#self-contained-deployments-include-the-selected-runtime Set the RuntimeFrameworkVersion] to 2.0.3
## Include <tt>GTANetworkAPI</tt> by adding reference to '''dotnet/runtime/Bootstrapper.dll'''
## Your <tt>mygamemode.csproj</tt> should look like this:
<pre>
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<TargetFramework>netcoreapp2.0</TargetFramework>
<RuntimeFrameworkVersion>2.0.3</RuntimeFrameworkVersion>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>None</ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>
</PropertyGroup>

<ItemGroup>
<Reference Include="GTANetworkAPI">
<HintPath>..\..\runtime\Bootstrapper.dll</HintPath> 
<Private Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">False</Private>
</Reference>
</ItemGroup>

</Project>
</pre>
Save the files and enter in terminal: <tt>></tt><code>dotnet restore</code>.

== Setting up Launch and Task command ==
Visual Studio Code comes with two kind of project commands: '''launch.json''' and '''tasks.json'''

These commands are saved inside a .vscode folder of your project, so you have to do this on every different projects you created.

=== launch.json ===
The launch command is used for running server debug with <kbd>F5</kbd> key (or from '''Debug''' menu) later

# Proceed to Debugging Tab (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>)
# Click the Gear button (next to DEBUG button) to configure the <tt>launch.json</tt>, select ''.NET Core'' or ''Others''
# Modify the configuration like this:
<pre>
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "RAGE-MP Launch (build)",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "compile",
"program": "server.exe", // The RAGEMP server executable
"args": [],
"cwd": "${workspaceFolder}/../../../", // Or absolute path to your X:/RAGEMP/server-files/
"stopAtEntry": false,
"console": "externalTerminal",
"internalConsoleOptions": "neverOpen"
}
]
}
</pre>
Save the <tt>launch.json</tt> file.

=== tasks.json ===
We will create two kind of tasks:
* '''compile''' - to compile the resource into <tt>.dll</tt>, required for debugging in launch task we created before (located in '''bin/Debug/''' by default)
* '''release''' - to build the end product of the resource with optimized <tt>.dll</tt> ready to deploy & run in real server (located in '''bin/Release/''' by default)

You can run these tasks by selecting '''Terminal'''>'''Run Task...''' later time.

# Select on menu bar '''Terminal'''>'''Configure Tasks...''', select ''.NET Core'' or ''Others''
# Modify the configuration like this:
<pre>
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "compile",
"type": "shell",
"command": "dotnet build",
"presentation": {
"reveal": "silent"
},
"problemMatcher": "$msCompile",
"group": {
"kind": "build",
"isDefault": true
},
"promptOnClose": true
},
{
"label": "release",
"type": "shell",
"command": "dotnet build -c Release",
"problemMatcher": "$msCompile",
"group": "build"
}
]
}
</pre>
Save the <tt>tasks.json</tt> file.

== Setting Up Resource ==
Now you can create your script in '''Class1.cs''', rename it if you wish (make sure the class name is also renamed)

=== Writing the gamemode ===
# Add the C# server-side bridge dependency with <code>using GTANetworkAPI</code>
# Extends your class to <tt>Script</tt> API like <code>public class Class1 : Script</code>
# Add <code>Hello World!</code> code in the entry point or class constructor of the script, your code would look like this:
<pre>
using System;
using GTANetworkAPI;

namespace mygamemode
{
public class Class1 : Script
{
public Class1()
{
Console.WriteLine("Hello World!");
}
}
}
</pre>
=== Configuring resource meta file ===
# Create a new file [https://wiki.gtanet.work/index.php?title=meta.xml meta.xml] in your resource folder (if not exist)
# Put some resource information, and add the <tt>mygamemode.dll</tt> file
<pre>
<meta>
<info name="My Gamemode" description="My C# bridge gamemode Resource" />



<script src="bin/Debug/netcoreapp2.0/mygamemode.dll" />
</meta>
</pre>
Note that after running compile task, your <tt>.cs</tt> scripts will be compiled into <tt>.dll</tt> by default located on <code>bin/Debug/netcoreapp2.0/</code> folder relative to your resource directory.

If you are not sure why your <tt>.dll</tt> does not work, try running the server with raw <tt>Class1.cs</tt> source code (uncomment the Uncompiled and comment the Compiled script tag).

=== Configuring bridge setting ===
# Edit '''bridge/[https://wiki.gtanet.work/index.php?title=settings.xml settings.xml]''' file in your server folder, add your resource like the following:
<pre>
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<acl_enabled>false</acl_enabled>
<resource src="mygamemode" />
</config>
</pre>
Save the files.

== Debugging the Script ==
When you are set up ready, it's time to build the resource!

If there are errors on compilation, try to close the folder and re-open it in your Visual Studio Code, usually the OmniSharp server need to refresh new files.

You can also try <tt>></tt><code>dotnet clean</code> in case you have changes on the referenced files (i.e. Bootstrapper update).

Since we have not added any gameplay code in this tutorial, we do not have to play & join the server.

# Open your script Class1.cs, add a code breakpoint by clicking on the left side of the line number
# For example, you may want to put a pause before the server prints "Hello World" line
<syntaxhighlight lang="csharp" highlight="10" start="8" line>
public Class1()
{
Console.WriteLine("Hello World!");
}
</syntaxhighlight>
# Go to Debug tab
# Hit <kbd>F5</kbd> button
# Your server will run, and the server threads will pause on your breakpoint line
# Click '''► Continue''' button (<kbd>F5</kbd>) on top of your Visual Studio window
# You will get output "Hello World" in your server console.
<pre>
Loading resources..
-> Starting mygamemode resource..
mygamemode: loading scripts...
mygamemode: instantiating mygamemode.Class1..
Hello world!
-> Resource mygamemode started!
</pre>
Close the server/hit the '''■ Stop''' debugging button (<kbd>Shift</kbd>+<kbd>F5</kbd>).

After you made changes to your script, you can always hit <kbd>F5</kbd> again to restart debugging.

== Deploying the Resource ==
Now that you have learn how to build and debug your script, later when your resource is ready, you may want to compile it with the Release task to deploy an optimized binary.

Simply, click on menu '''Terminal'''>'''Run Task...''' then select '''release'''

You can find your <tt>.dll</tt> in <code>bin/Release/netcoreapp2.0/</code> as you may notice it contains cleaner files, since we configured to not copy the <tt>.dll</tt> files from runtime folder with the <code><Private></code> option.
This build will be not debugable as the symbols are already removed and optimized for run time.

Proceed to upload these <tt>.dll</tt> file to your server, and be sure to set your '''meta.xml''' differently as it will be using the non-debugged version.
<pre>
<meta>
<info name="My Gamemode" description="My C# bridge gamemode Resource" />
<script src="bin/Release/netcoreapp2.0/mygamemode.dll" />
</meta>
</pre>

You might want to have the <tt>.pdb</tt> file together with it, it will create useful traceable dump in case your code causes server crash during runtime, even though it is not really possible to debug it.

== Client-side ==
You can also do similar thing to work with client-side scripts, except you do not deal with launch or task commands. However, please note that in RAGE MP Client-side C-Sharp scripts are NOT compiled nor build into <tt>.dll</tt>. Which means you cannot debug it like in this tutorial.

You can still make the project, reference to '''rage-sharp.dll''' in '''RAGEMP/dotnet/''' folder to get IntelliSense auto completion benefit in VSCode, similar way we did on Bootstrapper:
<pre>
<ItemGroup>
<Reference Include="RAGE">
<HintPath>..\..\..\dotnet\rage-sharp.dll</HintPath> 
<Private>False</Private>
</Reference>
</ItemGroup>
</pre>
And you just have to save the <tt>.cs</tt> file, they will be downloaded to your player's RAGE-MP client and will be compiled as how you configured it.

{| class="wikitable
|+ A brief comparison how C# works in RAGE-MP
|-
!
! Server-side Bridge (Compiled)
! Server-side (Raw)
! Client-side
|-
! Output
| [[wikipedia:Common Intermediate Language|IL]] "binary" (<tt>.dll</tt>)
| colspan="2" | C-Sharp source code (<tt>.cs</tt>)
|-
! Dependency
| colspan="2" | <tt>Bootstrapper.dll</tt> runtimes & <tt>bridge.dll</tt> plugin
| <tt>rage-sharp.dll</tt> runtimes
|-
! Compile Time
| By server developer with C# Compiler (in SDK)
| By <tt>server.exe</tt>
| By <tt>ragemp_v.exe</tt>
|-
! .NET Core Version
| colspan="2" | 2.0.3 <sup>1)</sup>
| 2.2.0 <sup>2)</sup>
|-
! Debugging
| Developer's debugger tool choice (in SDK)
| colspan="2" | RAGE MP app built in error handling & logging
|}
Notes:
* <sup>1)</sup> As of 0.3.7 based on <tt>.version</tt> file found in '''RAGEMP/server-files/bridge/runtime/''' folder
* <sup>2)</sup> As of 0.3.7 based on <tt>.version</tt> file found in '''RAGEMP/dotnet/''' folder

== See also ==
* [[Getting Started with Development]]
* [https://wiki.gtanet.work/index.php?title=Getting_Started_with_Development Getting started with Development on C# Bridge Server]
* [[Server-side events]] (or in [https://wiki.gtanet.work/index.php?title=Scripting_Events C#] bridge)
* [[Server-side functions]] (or in [https://wiki.gtanet.work/index.php?title=Server_Scripting_Functions C#] bridge)
* [[Client-side events]] (or in [[Client-side_CSharp_events|C#]])
* [[Client-side functions]] (or in [[Client-side_CSharp_functions|C#]])

[[Category:Tutorials]]

RAGE Multiplayer Wiki - User contributions [en]

Development with Visual Studio Code