⬆️From 0.0.24.x to 0.1.0 Beta 1

Guide for upgrading 0.0.24.x mods to Beta 1

This page lists all the changes that have been made from 0.0.24.x to 0.1.0 Beta 1. For upgrading your mods from 0.0.24.x directly to the 0.1.0 series, use the main upgrade page where it highlights the most important changes. We have made nine milestones prior to the first beta release.

From 0.0.24.x to Milestone 1

During Milestone 1's development, we have made the following breaking changes:

Moved events to `KS.Kernel.Events`

Events.vb

Public Class Events
    Friend Property FiredEvents As New Dictionary(Of String, Object())

    'These events are fired by their Raise<EventName>() subs and are responded by their Respond<EventName>() subs.
    Public Event KernelStarted()
    Public Event PreLogin()
    Public Event PostLogin(Username As String)
    (...)

EventsManager.vb

Public Function ListAllFiredEvents() As Dictionary(Of String, Object())
Public Function ListAllFiredEvents(SearchTerm As String) As Dictionary(Of String, Object())
Public Sub ClearAllFiredEvents()

All of the event-related code files are moved to KS.Kernel.Events to separate these from the actual kernel code. However, because events are part of the kernel, we prefer to put it on KS.Kernel namespace rather than KS.Misc.

Change the namespace declaration to refer to kernel events from KS.Misc to KS.Kernel.Events.

Moved `PlatformDetector` to `KS.Kernel.KernelPlatform`

PlatformDetector.vb

Public Module PlatformDetector

It has come to the conclusion that PlatformDetector is now promoted to the Kernel namespace under the name KernelPlatform so you can access it under the KS.Kernel namespace.

Change the namespace declaration to refer to kernel platform code from KS.Misc to KS.Kernel.KernelPlatform.

Separated the MOTD and MAL parsers

MOTDParse.vb

Public Enum MessageType As Integer

MOTD and MAL parsers were unified since early versions of Nitrocid KS. However, it didn't occur to us that we need to separate them for a very long time. We took actions to separate them, effectively removing the MessageType enumeration.

If you want to use the MOTD parser, use the KS.Misc.Probers.Motd namespace to use the MotdParse static class methods.
However, if you want to use the MAL parser, use the KS.Misc.Probers.Mal namespace to use the MalParse static class methods.

Moved `GetTerminal*` to `KernelPlatform`

ConsoleExtensions.vb

Public Function GetTerminalEmulator() As String
Public Function GetTerminalType() As String

These two functions are actually part of the terminal, and they make use of the $TERM_PROGRAM and $TERM environment variables, which are dependent on the terminal.

Since these usually are undefined in Windows, we put these functions to KernelPlatform to accommodate the change as platform-dependent, but we don't actually check for Linux to execute these functions, because some terminal emulators in Windows actually define these variables.

Change the namespace declaration to refer to kernel terminal detection code from KS.ConsoleBase to KS.Kernel.KernelPlatform.

Moved shell common folders to `KS.Shell.Shells`

This is to separate the shell code for each tool from their folders to a unified namespace, KS.Shell.Shells. It houses every shell for every tool. This is to make creation of built-in shells easier.

This means that *ShellCommon modules are moved to KS.Shell.Shells.* and every call to that module should be redirected to that namespace. The tools, however, stays intact.

Removed `MakePermanent()`

ColorTools.vb

Public Sub MakePermanent()

MakePermanent used to save all the colors to kernel configuration. This function was now removed as a result of recent configuration improvements.

We advice you to cease using this function.

Graduated `Configuration` to `KS.Kernel`

Config.vb

Namespace Misc.Configuration

This configuration logic was smart enough to be graduated, since it's the core function in the kernel. It's used everywhere, including the settings command, which is an application that lets you adjust settings on the go.

Graduated `FindSetting` and `CheckSettingsVariables`

SettingsApp.vb

Public Function FindSetting(Pattern As String, SettingsToken As JToken) As List(Of String)
Public Function CheckSettingsVariables() As Dictionary(Of String, Boolean)

These two functions were unrelated to the settings app, but FindSetting() was what KS.Misc.Settings.SettingsApp uses, and CheckSettingsVariables() was renamed to CheckConfigVariables() to accommodate with the graduation.

You can find these methods in the ConfigTools module located in the KS.Kernel.Configuration namespace.

ConfigTools.cs

public static List<InputChoiceInfo> FindSetting(string Pattern, JToken SettingsToken)
public static Dictionary<string, bool> CheckConfigVariables()

Moved power management functions to `KS.Kernel.Power`

These power management functions were there in KernelTools since the earliest version of KS. Now, they're relocated to KS.Kernel.Power.

Change the namespace declaration to refer to kernel power code from KS.Kernel.KernelTools to KS.Kernel.Power.

Removed `InitPaths` in favor of properties

Paths.vb

Sub InitPaths()

Now, we don't have to initialize paths every time we make an internal app that depends on Nitrocid KS's paths. The call to the function that gets the path, GetKernelPath, however won't be removed because it's widely used and is unaffected.

This function is not part of the public API. Reflection calls to this function will stop working. We advice you to use the GetKernelPath function since it's much faster.

Paths.cs

public static string GetKernelPath(KernelPathType PathType)

Moved kernel update code to `Kernel.Updates`

These power management functions were there in KernelTools since the earliest version of KS. Now, they're relocated to KS.Kernel.Updates.

Change the namespace declaration to refer to kernel update code from KS.Kernel.KernelTools to KS.Kernel.Updates.

From Milestone 1 to Milestone 2

During Milestone 2's development, we have made the following breaking changes:

Removed `ListArgs` from `ICommand` and `IArgument`

'ICommand.vb
Sub Execute(StringArgs As String, ListArgs As String(), ListArgsOnly As String(), ListSwitchesOnly As String())
                                  ^^^^^^^^^^^^^^^^^^^^

'IArgument.vb
Sub Execute(StringArgs As String, ListArgs As String(), ListArgsOnly As String(), ListSwitchesOnly As String())
                                  ^^^^^^^^^^^^^^^^^^^^

It seems that ListArgs is now no longer a reliable way to check for arguments, as it could be null when no argument is provided. While it contains a collection of switches and arguments, it's sequential. We have separated between switches and arguments as demonstrated in both the ListArgsOnly and ListSwitchesOnly arrays.

Recent changes to the shell command parsing code have allowed reliable argument and switch parsing. Use the ListArgsOnly and ListSwitchesOnly arrays to process arguments and switches.

Moved `GetEsc()` to `Misc.Text.CharManager`

Color255.vb

Public Function GetEsc() As Char

GetEsc() is now widely used for color manipulation, but we need to move it to a better place as migration to ColorSeq is done.

Color255.vb

Public Module Color255

We have deleted Color255 from KS.ConsoleBase as a result of this migration.

Change the namespace declaration to refer to GetEsc() from KS.ConsoleBase.Colors to KS.Misc.Text.CharManager.

From Milestone 2 to Milestone 3

During Milestone 3's development, we have made the following breaking changes:

Removed `FullArgumentList`

ProvidedCommandArgumentsInfo.vb

Public ReadOnly Property FullArgumentsList As String()

Following the removal of ListArgs(), we can safely remove this property.

Recent changes to the shell command parsing code have allowed reliable argument and switch parsing. Use the ListArgsOnly and ListSwitchesOnly arrays to process arguments and switches.

Removed `ConsoleWriters..WritePlain` in favor of the plain writers

The plain writer interfaces feel like they're a great addition to control the console writers.

Use the plain writers to replace the removed plain writers from the ConsoleWriters.

Updated debug and notifications namespaces

We felt that moving debug-related functions to KS.Kernel would be more convenient, so we moved these functions to it. Also, we've renamed the notifications namespace.

The below namespaces were affected in this change:

KS.Misc.Writers.DebugWriters -> KS.Kernel.Debugging
KS.Network.RemoteDebug -> KS.Kernel.Debugging.RemoteDebug
KS.Misc.Notifiers -> KS.Misc.Notifications

Merged `ParseCmd` with `ExecuteCommand`

RemoteDebugCmd.vb

Sub ParseCmd(CmdString As String, SocketStreamWriter As StreamWriter, Address As String)

It has come to the conclusion that ParseCmd is now very similar to ExecuteCommand with treating the remote debug shell specially. This is no longer needed as ProvidedCommandArgumentsInfo has been provided the IP address of the target device, making ParseCmd redundant.

This function wasn't part of the public KS API. We advice you to cease using this function and start declaring your remote debug command.

Removed `ExecuteRDAlias()`

AliasExecutor.vb

Sub ExecuteRDAlias(aliascmd As String, SocketStream As IO.StreamWriter, Address As String)

This function was not needed to execute aliases since there has been recent improvements to the executor in both 0.0.20.0 and 0.0.24.0.

This function wasn't part of the public KS API. We advice you to cease using this function.

From Milestone 3 to Milestone 4

During Milestone 4's development, we have made the following breaking changes:

Renamed debug writer function names

DebugWriter.vb

Public Sub Wdbg(Level As DebugLevel, text As String, ParamArray vars() As Object)
Public Sub WdbgConditional(ByRef Condition As Boolean, Level As DebugLevel, text As String, ParamArray vars() As Object)
Public Sub WdbgDevicesOnly(Level As DebugLevel, text As String, ParamArray vars() As Object)
Public Sub WStkTrcConditional(ByRef Condition As Boolean, Ex As Exception)
Public Sub WStkTrc(Ex As Exception)

We needed to do the same thing as we've renamed W() to Write(), so we renamed the following:

Wdbg() -> WriteDebug()
WdbgConditional() -> WriteDebugConditional()
WdbgDevicesOnly() -> WriteDebugDevicesOnly()
WStkTrcConditional() -> WriteDebugStackTraceConditional()
WStkTrc() -> WriteDebugStackTrace()

You can use these functions to write debugging information in your mods to the kernel debugger. The below method signatures are provided:

DebugWriter.cs

public static void WriteDebug(DebugLevel Level, string text, params object[] vars)
public static void WriteDebugConditional(bool Condition, DebugLevel Level, string text, params object[] vars)
public static void WriteDebugDevicesOnly(DebugLevel Level, string text, params object[] vars)
public static void WriteDebugStackTraceConditional(bool Condition, Exception Ex)
public static void WriteDebugStackTrace(Exception Ex)

Moved MAL and MOTD message to `Misc.Probers.Motd`

Kernel.vb

Public MOTDMessage, MAL As String

These have no relationship with the kernel directly.

If you need to set the MOTD and MAL messages, you need to use the SetMotd() and SetMal() functions.

Moved `HostName` from Kernel to `NetworkTools`

Kernel.vb

Public HostName As String

It has no relationship with the kernel either.

If you need to change the hostname, you need to use the ChangeHostname function in NetworkTools.

NetworkTools.cs

public static void ChangeHostname(string NewHost)

From Milestone 4 to Milestone 5

During Milestone 5's development, we have made the following breaking changes:

Renamed permissions to groups

PermissionManagement.cs

public static class PermissionManagement

We have renamed the permissions feature to groups to avoid confusion. Later, it's been renamed to user flags in later development versions.

From Milestone 5 to Milestone 7

During Milestone 7's development, we have made the following breaking changes:

Made abstractions regarding the color management class

The color management used to define so many variables for just one color type. Now, it has been simplified to ease the making of the new color type. Color types are renamed to match all files that mention the color type.

As a result, we have removed all separate variables for each color type and merged them to simplify the declaration.

Also, we have added GetColor() and SetColor() functions to ColorTools to perform operations on these color types.

Moved `ConfigCategory` outside `Config` class

Config.vb

Public Enum ConfigCategory

We have moved ConfigCategory outside the Config class to better organize the enumerations relating to the configuration.

Use `CommandArgumentInfo` in arguments

ArgumentInfo.vb

Public Sub New(Argument As String, Type As ArgumentType, HelpDefinition As String, HelpUsage As String, ArgumentsRequired As Boolean, MinimumArguments As Integer, ArgumentBase As ArgumentExecutor, Optional Obsolete As Boolean = False, Optional AdditionalHelpAction As Action = Nothing)

Using CommandArgumentInfo allows you to define argument information for commands. However, it's a powerful class for managing arguments for commands and kernel arguments themselves.

As a result, we've used CommandArgumentInfo in ArgumentInfo.

You need to change how you call the constructor of ArgumentInfo to hold the CommandArgumentInfo instance.

ArgumentInfo.cs

public ArgumentInfo(string Argument, string HelpDefinition, CommandArgumentInfo ArgArgumentInfo, ArgumentExecutor ArgumentBase, bool Obsolete = false, Action AdditionalHelpAction = null)

Removed `SetColors` as they're no longer used

ColorTools.vb

Public Function TrySetColors(InputColor As String, LicenseColor As String, ContKernelErrorColor As String, UncontKernelErrorColor As String, HostNameShellColor As String, UserNameShellColor As String,
                             BackgroundColor As String, NeutralTextColor As String, ListEntryColor As String, ListValueColor As String, StageColor As String, ErrorColor As String, WarningColor As String,
                             OptionColor As String, BannerColor As String, NotificationTitleColor As String, NotificationDescriptionColor As String, NotificationProgressColor As String,
                             NotificationFailureColor As String, QuestionColor As String, SuccessColor As String, UserDollarColor As String, TipColor As String, SeparatorTextColor As String,
                             SeparatorColor As String, ListTitleColor As String, DevelopmentWarningColor As String, StageTimeColor As String, ProgressColor As String, BackOptionColor As String,
                             LowPriorityBorderColor As String, MediumPriorityBorderColor As String, HighPriorityBorderColor As String, TableSeparatorColor As String, TableHeaderColor As String,
                             TableValueColor As String, SelectedOptionColor As String, AlternativeOptionColor As String) As Boolean
Public Sub SetColors(InputColor As String, LicenseColor As String, ContKernelErrorColor As String, UncontKernelErrorColor As String, HostNameShellColor As String, UserNameShellColor As String,
                     BackgroundColor As String, NeutralTextColor As String, ListEntryColor As String, ListValueColor As String, StageColor As String, ErrorColor As String, WarningColor As String,
                     OptionColor As String, BannerColor As String, NotificationTitleColor As String, NotificationDescriptionColor As String, NotificationProgressColor As String,
                     NotificationFailureColor As String, QuestionColor As String, SuccessColor As String, UserDollarColor As String, TipColor As String, SeparatorTextColor As String,
                     SeparatorColor As String, ListTitleColor As String, DevelopmentWarningColor As String, StageTimeColor As String, ProgressColor As String, BackOptionColor As String,
                     LowPriorityBorderColor As String, MediumPriorityBorderColor As String, HighPriorityBorderColor As String, TableSeparatorColor As String, TableHeaderColor As String,
                     TableValueColor As String, SelectedOptionColor As String, AlternativeOptionColor As String)

We have improved the color tools module, so SetColors is no longer used. We've removed it for this reason. Use SetColor() instead.

To set the kernel type to a specified color, use SetColor().

ColorTools.cs

public static Color SetColor(KernelColorType type, Color color)

Changed algorithm enum to EncryptionAlgorithms

Encryption.vb

Public Enum Algorithms

As part of an ongoing change to the encryption driver, we've changed the algorithm enumeration to EncryptionAlgorithms outside the Encryption module.

Encryption driver no longer uses the EncryptionAlgorithms enumeration, although it now handles custom algorithms. The enumeration can't be used anymore.

From Milestone 7 to Milestone 8

During Milestone 8's development, we have made the following breaking changes:

Public Class ShellInfo
Public MustInherit Class ShellExecutor
    Implements IShell

We have renamed the below two shell-related classes to the ones that suit the narrative of the classes.

These classes can still be called using the following names:

ShellInfo -> ShellExecuteInfo
ShellExecutor -> BaseShell

Moved `TextLocation` to `Misc.Text`

TextLocation.vb

Public Enum TextLocation

This is a text-related enumeration of text vertical location (top, bottom). It's used by the splashes.

Change the namespace declaration to refer to this enumeration from KS.Misc to KS.Misc.Text.

Moved `GetCommands` to `CommandManager`

GetCommand.vb

Public Function GetCommands(ShellType As ShellType) As Dictionary(Of String, CommandInfo)

This sub is more of a command management routine than the "getting command" module work itself.

GetCommands() has been moved from GetCommand module to CommandManager module.

Changed the entire event system

Events.vb

Public Class Events

Kernel.vb

Public ReadOnly KernelEventManager As New Events

We have moved all the events to its own dedicated array containing all the available events that the kernel introduced, removing the giant Events class and its variable, KernelEventManager, in the Kernel entry point class. This will reduce the need of importing the Kernel namespace and class everytime we need to directly manage the events.

Event firing and response functions are moved to the EventsManager class in one function, FireEvent.

To fire events, you now have to use the FireEvent function found under the EventsManager module. Its method signature is printed below:

EventsManager.cs

public static void FireEvent(EventType Event, params object[] Params)

Moved `NewLine` from `Kernel` to `CharManager`

Kernel.vb

Public ReadOnly NewLine As String

This is actually a character management function and not a function directly to the kernel.

This variable is now found under KS.Misc.Text.CharManager.

This has to do with the user management namespace, so we moved it to that namespace.

Change the namespace declaration to refer to this enumeration from KS.Login to KS.Users.Login.

Moved `Kernel[Api]Version` to `KernelTools`

Kernel.vb

'From 0.0.24.0
Public ReadOnly KernelVersion As String

We didn't want the Kernel class to be publicly accessible, since it has been planned back at 0.0.1 as the class responsible for being an entry point. As a result, these variables, KernelVersion and KernelApiVersion, were successfully moved to KernelTools.

To use these variables in their new location, change the reference from Kernel to KernelTools.

Removed `ColoredShell`

Shell.vb

Public ColoredShell As Boolean

The colors are now an essential part of KS, so we decided to take out support for uncolored shell.

Finally condensed `TableColor`

TableColor.vb

Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, Color As ConsoleColor, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, ForegroundColor As ConsoleColor, BackgroundColor As ConsoleColor, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, ColTypes As ColTypes, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, colorTypeForeground As ColTypes, colorTypeBackground As ColTypes, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, Color As Color, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)
Public Sub WriteTable(Headers() As String, Rows(,) As String, Margin As Integer, ForegroundColor As Color, BackgroundColor As Color, Optional SeparateRows As Boolean = True, Optional CellOptions As List(Of CellOptions) = Nothing)

We noticed that the code is repetitive for making tables, and we don't want to update six locations every bug fix, so we decided to condense it to a single code.

As a side-effect, we've changed the color signatures from foreground and background pairs to header, value, separator, and background colors. Consequently, we've removed the ConsoleColor version of TableColor as we found it irrelevant thanks to the enhanced Color class found in the Terminaux library.

Use the new method signatures to write your table. As for the ConsoleColor version, we advice you to upgrade to ConsoleColors at minimum.

TableColor.cs

public static void WriteTable(string[] Headers, string[,] Rows, int Margin, bool SeparateRows = true, List<CellOptions> CellOptions = null)
public static void WriteTable(string[] Headers, string[,] Rows, int Margin, KernelColorType colorTypeSeparatorForeground, KernelColorType colorTypeHeaderForeground, KernelColorType colorTypeValueForeground, KernelColorType colorTypeBackground, bool SeparateRows = true, List<CellOptions> CellOptions = null)
public static void WriteTable(string[] Headers, string[,] Rows, int Margin, ConsoleColors SeparatorForegroundColor, ConsoleColors HeaderForegroundColor, ConsoleColors ValueForegroundColor, ConsoleColors BackgroundColor, bool SeparateRows = true, List<CellOptions> CellOptions = null)
public static void WriteTable(string[] Headers, string[,] Rows, int Margin, Color SeparatorForegroundColor, Color HeaderForegroundColor, Color ValueForegroundColor, Color BackgroundColor, bool SeparateRows = true, List<CellOptions> CellOptions = null)

Tried to balance color support for writers

Migration from ConsoleColor to ConsoleColors is complete. This means that all the writers in the KS.Misc.*Writers now have the ConsoleColors support.

The latest ColorSeq version, 1.0.2, will be used to make it easier to achieve.

It's best to upgrade your ConsoleColor variables to ConsoleColors at minimum.

Added last argument support to auto completer

CommandArgumentInfo.cs

public Func<string[]> AutoCompleter { get; private set; }

We've added support for the last argument written to aid the auto completer in completing the command according to the last argument written. This is to ensure completions in the right context.

If your command needs this feature, it's best to implement it.

From Milestone 8 to Milestone X

During Milestone X's development, we have made the following breaking changes:

Renamed command executor and base to reduce confusion

Public Module GetCommand
Public MustInherit Class CommandExecutor
    Implements ICommand

Base command class had the name of CommandExecutor. However, it behaved like the base class for your mod commands, so we renamed it to BaseCommand. This caused us to rename the command execution class to CommandExecutor.

To use the new names, you have to rename the following in this order:

CommandExecutor -> BaseCommand
GetCommand -> CommandExecutor

Renamed `ConsoleSanityChecker` to `ConsoleChecker`

ConsoleSanityChecker.vb

Public Module ConsoleSanityChecker

This class will be filled by many console checks, so renamed it according to the purpose.

To use the methods inside the class, rename the references from ConsoleSanityChecker -> ConsoleChecker.

`WriteWherePlain` from `TextWriterWhereColor` renamed

TextWriterWhereColor.vb

Public Sub WriteWherePlain(msg As String, Left As Integer, Top As Integer, ParamArray vars() As Object)
Public Sub WriteWherePlain(msg As String, Left As Integer, Top As Integer, [Return] As Boolean, ParamArray vars() As Object)

This change is necessary to fit in with the rest of the ConsoleWriters

To continue using the plain writer, rename the references from WriteWherePlain -> WriteWhere.

Removed `Screensaver.colors`

Screensaver.vb

Public ReadOnly colors() As ConsoleColor = CType([Enum].GetValues(GetType(ConsoleColor)), ConsoleColor())
Public ReadOnly colors255() As ConsoleColors = CType([Enum].GetValues(GetType(ConsoleColors)), ConsoleColors())

This is to remove support for 255 colors in screensavers.

We advice you to cease using this function.

Moved `KS.Network` classes to `KS.Network.Base`

Public Module NetworkAdapter
Public Module NetworkAdapterPrint
Public Module NetworkTools

These classes are believed to be the base classes for the networking. These classes are used for general networking purposes.

Change the namespace declaration to refer to this enumeration from KS.Network to KS.Network.Base.

Condensed speed dial to `KS.Network.SpeedDial`

The speed dial API wasn't touched for a long time, so we decided to condense the speed dial API to a single namespace to ease the addition of the speed dial feature to all the networking shells.

In consequence, the speed dial format has changed.

Old format

  "ftp.riken.jp": {
    "Address": "ftp.riken.jp",
    "Port": 21,
    "User": "anonymous",
    "Type": 0,
    "FTP Encryption Mode": 0
  },

New format

  "ftp.us.debian.org": {
    "Address": "ftp.us.debian.org",
    "Port": 21,
    "Type": 0,
    "Options": [
      "anonymous",
      0
    ]
  }

The username and FTP encryption mode is now moved to Options, which is an array of options that the networking shells use. To convert your speed dial entries, you have to manually open all FTP and SFTP speed dial JSON files and make changes to transition from the old format to the new format.

Moved network transfer functions to `KS.Network.Base.Transfer`

Public Module NetworkTransfer
Public Class NetworkTransferInfo
Public Enum NetworkTransferType

We've done that to the base network classes, so why not do the same to the network transfer functions?

Change the namespace declaration to refer to this enumeration from KS.Network.Transfer to KS.Network.Base.Transfer.

Kernel exception handling changed

We have changed the way how the kernel exception handling works. We have simplified the code, merging all the exception classes to just one enumeration to help you filter kernel exceptions matching a specific exception.

This also helps us in making dynamic suggestions to specific error type in the future.

As a consequence, mods that use old handling now break, and should use this format to continue working as usual:

catch (KernelException ke) when (ke.ExceptionType == KernelExceptionType.ErrorType)

...where ErrorType is an error type obtained from the KernelExceptionType enumeration.

Changed `GetFilteredPositions` to tuple

ConsoleExtensions.vb

Public Sub GetFilteredPositions(Text As String, ByRef Left As Integer, ByRef Top As Integer, ParamArray Vars() As Object)

To aid in simplicity of the function, we've replaced the two reference variables with the tuples in their respective orders of cursor left and top positions.

The first tuple value in the returned value specifies the filtered X position, and the second one specifies the filtered Y position in the console buffer.

ConsoleExtensions.cs

public static (int, int) GetFilteredPositions(string Text, params object[] Vars)

Internalized several kernel tools

KernelTools.vb

Public Sub KernelError(ErrorType As KernelErrorLevel, Reboot As Boolean, RebootTime As Long, Description As String, Exc As Exception, ParamArray Variables() As Object)
Sub GeneratePanicDump(Description As String, ErrorType As KernelErrorLevel, Exc As Exception)
Sub ResetEverything()
Sub InitEverything(Args() As String)
Sub FactoryReset()
Sub ReportNewStage(StageNumber As Integer, StageText As String)

These tools could be abused, so we decided to privatize these tools.

We advice you to cease using these functions.

Removed `PrepareDict`

Translate.vb

Public Function PrepareDict(lang As String) As Dictionary(Of String, String)

PrepareDict used to populate the string dictionary with definitions to the localized string. Now, because the language management routine was remodeled, we've removed PrepareDict as part of the change.

The language manager automatically does this each time your mod sets the language, so we advice you to cease using this function.

Removed network adapter querying

'NetworkAdapter.vb
Public Function IsInternetAdapter(InternetAdapter As NetworkInterface) As Boolean

'NetworkAdapterPrint.vb
Public Sub PrintAdapterProperties()
Sub PrintAdapterIPv4Info(NInterface As NetworkInterface, Properties As IPv4InterfaceProperties, Statistics As IPv4InterfaceStatistics, AdapterNumber As Long)
Sub PrintAdapterIPv6Info(NInterface As NetworkInterface, Properties As IPv6InterfaceProperties, AdapterNumber As Long)
Sub PrintGeneralNetInfo(IPv4Stat As IPGlobalStatistics, IPv6Stat As IPGlobalStatistics)

The network adapter querying functionality was implemented in 0.0.3. This functionality was no longer maintained as it wasn't tweaked.

We advice you to cease using this functionality.

Theme preview is no longer exclusive to theme studio

ThemeStudioTools.vb

Sub PreparePreview()

The theme preview routine used to depend on the theme studio to do its job, under the name of ThemeStudioTools.PreparePreview(). However, because there were recent improvements to the theming system, we've finally condensed the preview routine to ThemeTools.PreviewTheme(). You can no longer use the old method, because it also required loading the theme information to the theme studio itself. What if it was called in a context that has no relationship with the theme studio, such as in the case of themesel?

You can use the new ThemeTools.PreviewTheme() function to preview any theme. The method signatures are written below.

ThemeTools.cs

public static void PreviewTheme(string theme)
public static void PreviewTheme(ThemeInfo theme)
public static void PreviewTheme(Dictionary<KernelColorType, Color> colors)

Migrated kernel arguments

Public Enum ArgumentType
Public Module CommandLineArgs
Public Module ArgumentPrompt

We used to provide two argument channels: one for the command-line kernel arguments, and one for the kernel arguments. The entry point has been provided the Args variable to get all the arguments from the command line. Since it has undergone recent improvements to the system, we've decided to remove the kernel arguments channel, so we don't have to parse the passed arguments twice.

We also had to remove the arginj command, one of the commands that made appearance in first-generation versions of KS.

Removed `GetCompilerVars`

KernelTools.vb

Public Function GetCompilerVars() As String()

This was only useful in conditions where getting the compiler variables for determining the kernel milestone is needed, which was seldom needed by mods. We've removed it.

We advice you to cease using this function.

Migrated encryptors to Kernel Drivers

The kernel drivers are beneficial, so we decided to give the encryptors a chance to appear in kernel drivers. This caused us to remove EncryptionAlgorithms and IEncryptor and replace them with IEncryptionDriver, handled by the kernel driver handler.

You can implement your own encryptor by registering your custom encryption driver using the RegisterDriver function.

DriverHandler.cs

public static void RegisterDriver(DriverTypes type, IDriver driver)

Removed `TwoNewlines` argument from `WriteLicense`

WelcomeMessage.vb

Sub WriteLicense(TwoNewlines As Boolean)

This argument was unused, so we decided to remove it from WriteLicense().

We advice you to cease using this variable.

Renamed `PartInfo` to `ModPartInfo`

PartInfo.vb

Public Class PartInfo

Add Mod next to PartInfo to clarify which module uses this.

To implement your new mod parts, construct the ModPartInfo class. For existing mod parts, rename PartInfo to ModPartInfo.

Manual pages moved to `Modifications`

Public Class Manual
Public Module PageManager
Module PageParser
Public Module PageViewer

These manual pages are used by mods to host documentation, so we moved it to KS.Modifications.ManPages to reflect its purpose.

Change the namespace declaration to refer to this enumeration from KS.ManPages to KS.Modifications.ManPages.

Changed `Notifications` to `NotificationManager`

Notifications.vb

Public Module Notifications

We felt that both the Notification and Notifications classes are confusing for some people, so we decided to make these clearer by renaming the Notifications class to NotificationManager

To use the methods inside the class, rename the references from Notifications -> NotificationManager.

Removed getting property value in variable

PropertyManager.vb

Public Function GetPropertyValueInVariable(Variable As String, [Property] As String) As Object
Public Function GetPropertyValueInVariable(Variable As String, [Property] As String, VariableType As Type) As Object

VariableProperty is no longer used, so we decided to remove it. As a consequence, we also had to remove the PropertyManager.GetPropertyValueInVariable() routine.

We advise you to cease using these functions.

From Milestone X to Beta 1

During Beta 1's development, we have made the following breaking changes:

Moved `ColTypes` to `KernelColorType`

ColorTools.vb

Public Enum ColTypes As Integer

This is an enumeration which simply tells the difference of all the defined and known kernel color types. We have moved ColTypes to KernelColorType.

To continue using the kernel color type enumeration, rename the references from ColTypes to KernelColorType, importing the KS.ConsoleBase.Colors namespace.

KernelColorType.cs

public enum KernelColorType

Removed `ref` from conditional debug writers

DebugWriter.vb

Public Sub WdbgConditional(ByRef Condition As Boolean, Level As DebugLevel, text As String, ParamArray vars() As Object)
Public Sub WStkTrcConditional(ByRef Condition As Boolean, Ex As Exception)

The conditional debug writers didn't do anything to the boolean condition that caused it to change its state, so we decided to pass the boolean value by value and not by reference.

Remove the ref prefix from the boolean variable that is being tested from your conditional debug writer calls. Follow the below method signatures:

DebugWriters.cs

public static void WriteDebugConditional(bool Condition, DebugLevel Level, string text, params object[] vars)
public static void WriteDebugStackTraceConditional(bool Condition, Exception Ex)

Removed `GroupManagement` (a.k.a. `PermissionManagement`)

PermissionManagement.vb

Public Module PermissionManagement

The GroupManagement module was removed in preparation for the new permission system. The groups were moved outside in the users JSON file to become singular boolean variables, and the permission system was implemented under the KS.Users.Permissions namespace.

To grant or revoke individual permissions from a specified user, use the following functions:

GrantPermission
RevokePermission

You may need to import the KS.Users.Permissions namespace to use this feature, although it works on all permissions, unlike the superuser variable which grants all permissions.

Their method signatures are written below.

PermissionsTools.cs

public static void GrantPermission(string User, PermissionTypes permissionType)
public static void RevokePermission(string User, PermissionTypes permissionType)

Removed obsolete functions

'Input.vb
Public Function ReadLineUntil(ByRef Condition As Boolean) As String

'ThreadManager.vb
Public Sub SleepNoBlock(Time As Long, ThreadWork As BackgroundWorker)

'NetworkTools.vb
Public Sub ConvertSpeedDialEntries(SpeedDialType As SpeedDialType)

ReadLineUntil(), SleepNoBlock(), and ConvertSpeedDialEntries() were removed for being obsolete. The first function was removed in favor of ReadLine.Reboot and TermRead, the second function was removed for the absence of our usage of BackgroundWorker, and the third function was removed as a result of huge improvements to the speed dial functionality that makes it incompatible with the older speed dial format.

We advice you to cease using these functions.

To sleep without blocking, convert all your BackgroundWorkers to KernelThread and use the appropriate SleepNoBlock overload for your kernel thread. The below method signature is shown.

ThreadManager.cs

public static void SleepNoBlock(long Time, KernelThread ThreadWork)

Argument auto-completion re-implemented

CommandArgumentInfo.vb

Public Sub New(HelpUsages() As String, ArgumentsRequired As Boolean, MinimumArguments As Integer, Optional AutoCompleter As Func(Of String()) = Nothing)

Command auto-completion used to be available on ReadLine.Reboot to automatically complete the command needed to run. However, ReadLine.Reboot has come to an end, so we decided to re-implement it to align with TermRead.

As a result, the auto completion facility in your shell, if it has one implemented in your CommandArgumentInfo, will have to be re-implemented to parse the whole command passed to the auto-completion builder, AutoCompleter, and generate suggestions based on that data.

In your CommandInfo implementation of your command, you'll also have to re-implement it so that the auto-completer takes three arguments. You can always discard the index and delimiters argument in your action declaration: (Text, _, _) => Function(Text).

CommandArgumentInfo.cs

public CommandArgumentInfo(string[] Arguments, SwitchInfo[] Switches, bool ArgumentsRequired, int MinimumArguments, bool AcceptsSet = false, Func<string, int, char[], string[]> AutoCompleter = null)

Converted kernel exceptions

Previously, we've used the built-in .NET exceptions to catch appropriate exceptions based on the context of an error. Since KernelException was implemented as part of the first development semester of Nitrocid KS 0.1.0, we decided to throw all the exceptions to KernelException that dynamically provides extended information as to what's wrong, coupled together with possible suggestions and extra messages.

In order to throw these exceptions, you must now route all your exception handlers in your mods to target KernelException and check the exception type before you can take action. Converted exceptions are found in this commit.

Removed decisive writers

Decisive.vb

Public Sub DecisiveWrite(CommandType As ShellType, DebugDeviceSocket As StreamWriter, Text As String, Line As Boolean, colorType As ColTypes, ParamArray vars() As Object)

We used to implement the decisive writers to decide whether to use the normal console writer or to use the remote debug connection according to the shell type. Over time, the remote debug shell was removed and later implemented as a standalone add-on for the remote debugger. This leads to us removing this decisive writer from the MiscWriters namespace.

We advice you to cease using this function.

Moved `PlaceParse` to `KS.Misc.Probers.Placeholder`

PlaceParse.vb

Public Module PlaceParse

This module used to statically replace all the text placeholders found within the text with their values. It used to exist in the KS.Misc.Probers namespace, but we moved it to the KS.Misc.Probers.Placeholder namespace to align with the latest Nitrocid KS API design. It also earned a new way to dynamically parse the placeholders.

The function names and the module itself are unchanged, but we just need you to change the namespace import to the abovementioned namespace.

Removed `KernelColorType.Gray`

ColorTools.vb

''' <summary>
''' Gray color (for special purposes)
''' </summary>
Gray

This color type was used as a special color type intended to indicate that the element highlighted is colorless. Since we already have ColorTools.GetGray() to get the gray color according to the background color, and since this color type is just a wrapper to this function, we decided to remove this kernel color type.

Instead of using KernelColorType.Gray, use the ColorTools.GetGray() function to get the gray color.

Replaced `GetVariables()` with `Variables` property

UESHVariables.vb

Public Function GetVariables() As Dictionary(Of String, String)

This function used to return a list of available UESH variables. It's been replaced with a property that does exactly the same thing. It's to make your mod code related to UESH variables easier to read.

Replace all calls to UESHVariables.GetVariables() with Variables.

HelpSystem.vb

Public Sub ShowHelp(command As String, CommandType As ShellType, Optional DebugDeviceSocket As StreamWriter = Nothing)
                                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remote debug shell used to require the DebugDeviceSocket parameter to be passed to ShowHelp for DecisiveWriter to decide what type of console is going to be written to. Since DecisiveWriter got removed and the remote debug shell was re-implemented to be standalone, we decided to remove this parameter.

There was no need to pass DebugDeviceSocket to this function anyways. If you really need to use it, make your own remote debug command with the help entry, and Nitrocid KS will take care of the rest.

Renamed few classes

TimeDate.vb

Namespace TimeDate
    Public Module TimeDate

IScript.vb

Namespace Modifications
    Public Interface IScript

TimeDate used to host all the time and date general properties and functions. However, its access required to reference the namespace and then the class, because both the namespace and the class have the same name. As a result, the TimeDate class is renamed to TimeDateTools for easier access.

Also, IScript used to be the heart of the kernel modifications. It's renamed to IMod since it doesn't have to do with the UESH scripts.

Your mods should change the implementation interface name of the mod, IScript, to the new name, IMod, as it's more fitting. This will break all mods.

For the time and date functions, use the new class name, TimeDateTools.

None of the methods and properties on the two above classes are changed.

PreviousUpgrading to API v3.0 series NextFrom 0.1.0 Beta 1 to 0.1.0 Beta 2

Last updated 1 month ago

From 0.0.24.x to Milestone 1

Moved events to KS.Kernel.Events

Moved PlatformDetector to KS.Kernel.KernelPlatform

Separated the MOTD and MAL parsers

Moved GetTerminal* to KernelPlatform

Moved shell common folders to KS.Shell.Shells

Removed MakePermanent()

Graduated Configuration to KS.Kernel

Graduated FindSetting and CheckSettingsVariables

Moved power management functions to KS.Kernel.Power

Removed InitPaths in favor of properties

Moved kernel update code to Kernel.Updates

From Milestone 1 to Milestone 2

Removed ListArgs from ICommand and IArgument

Moved GetEsc() to Misc.Text.CharManager

From Milestone 2 to Milestone 3

Removed FullArgumentList

Removed ConsoleWriters.*.Write*Plain in favor of the plain writers

Updated debug and notifications namespaces

Merged ParseCmd with ExecuteCommand

Removed ExecuteRDAlias()

From Milestone 3 to Milestone 4

Renamed debug writer function names

Moved MAL and MOTD message to Misc.Probers.Motd

Moved HostName from Kernel to NetworkTools

From Milestone 4 to Milestone 5

Renamed permissions to groups

From Milestone 5 to Milestone 7

Made abstractions regarding the color management class

Moved ConfigCategory outside Config class

Use CommandArgumentInfo in arguments

Removed SetColors as they're no longer used

Changed algorithm enum to EncryptionAlgorithms

From Milestone 7 to Milestone 8

Renamed two classes related to shell

Moved TextLocation to Misc.Text

Moved GetCommands to CommandManager

Changed the entire event system

Moved NewLine from Kernel to CharManager

Moved KS.Login to KS.Users.Login

Moved Kernel[Api]Version to KernelTools

Removed ColoredShell

Finally condensed TableColor

Tried to balance color support for writers

Added last argument support to auto completer

From Milestone 8 to Milestone X

Renamed command executor and base to reduce confusion

Renamed ConsoleSanityChecker to ConsoleChecker

WriteWherePlain from TextWriterWhereColor renamed

Removed Screensaver.colors

Moved KS.Network classes to KS.Network.Base

Condensed speed dial to KS.Network.SpeedDial

Moved network transfer functions to KS.Network.Base.Transfer

Kernel exception handling changed

Changed GetFilteredPositions to tuple

Internalized several kernel tools

Removed PrepareDict

Removed network adapter querying

Theme preview is no longer exclusive to theme studio

Migrated kernel arguments

Removed GetCompilerVars

Migrated encryptors to Kernel Drivers

Removed TwoNewlines argument from WriteLicense

Renamed PartInfo to ModPartInfo

Manual pages moved to Modifications

Changed Notifications to NotificationManager

Removed getting property value in variable

From Milestone X to Beta 1

Moved ColTypes to KernelColorType

Removed ref from conditional debug writers

Removed GroupManagement (a.k.a. PermissionManagement)

Removed obsolete functions

Argument auto-completion re-implemented

Converted kernel exceptions

Removed decisive writers

Moved PlaceParse to KS.Misc.Probers.Placeholder

Removed KernelColorType.Gray

Replaced GetVariables() with Variables property

Removed remote-debug-related argument from ShowHelp()

Renamed few classes

Moved events to `KS.Kernel.Events`

Moved `PlatformDetector` to `KS.Kernel.KernelPlatform`

Moved `GetTerminal*` to `KernelPlatform`

Moved shell common folders to `KS.Shell.Shells`

Removed `MakePermanent()`

Graduated `Configuration` to `KS.Kernel`

Graduated `FindSetting` and `CheckSettingsVariables`

Moved power management functions to `KS.Kernel.Power`

Removed `InitPaths` in favor of properties

Moved kernel update code to `Kernel.Updates`

Removed `ListArgs` from `ICommand` and `IArgument`

Moved `GetEsc()` to `Misc.Text.CharManager`

Removed `FullArgumentList`

Removed `ConsoleWriters..WritePlain` in favor of the plain writers

Merged `ParseCmd` with `ExecuteCommand`

Removed `ExecuteRDAlias()`

Moved MAL and MOTD message to `Misc.Probers.Motd`

Moved `HostName` from Kernel to `NetworkTools`

Moved `ConfigCategory` outside `Config` class

Use `CommandArgumentInfo` in arguments

Removed `SetColors` as they're no longer used

Moved `TextLocation` to `Misc.Text`

Moved `GetCommands` to `CommandManager`

Moved `NewLine` from `Kernel` to `CharManager`

Moved `KS.Login` to `KS.Users.Login`

Moved `Kernel[Api]Version` to `KernelTools`

Removed `ColoredShell`

Finally condensed `TableColor`

Renamed `ConsoleSanityChecker` to `ConsoleChecker`

`WriteWherePlain` from `TextWriterWhereColor` renamed

Removed `Screensaver.colors`

Moved `KS.Network` classes to `KS.Network.Base`

Condensed speed dial to `KS.Network.SpeedDial`

Moved network transfer functions to `KS.Network.Base.Transfer`

Changed `GetFilteredPositions` to tuple

Removed `PrepareDict`

Removed `GetCompilerVars`

Removed `TwoNewlines` argument from `WriteLicense`

Renamed `PartInfo` to `ModPartInfo`

Manual pages moved to `Modifications`

Changed `Notifications` to `NotificationManager`

Moved `ColTypes` to `KernelColorType`

Removed `ref` from conditional debug writers

Removed `GroupManagement` (a.k.a. `PermissionManagement`)

Moved `PlaceParse` to `KS.Misc.Probers.Placeholder`

Removed `KernelColorType.Gray`

Replaced `GetVariables()` with `Variables` property

Removed remote-debug-related argument from `ShowHelp()`