[Add] Neo Build Error Definition - Part 1

[cschuchardt88]

Blocks

• [Add] Neo Build Error Base - Part 2 #3730
• [Add] File Not Found Exception - Part 3 #3734
• [Add] File Denied Exception - Part 3 #3733

---

Error Codes

are used when an Exception is thrown, to identify known issues with building, deploying or testing project's *.nbproj file or MSBuild tasks within Visual Studio or dotnet CLI.

How to use Error Codes

When an Exception occurs (whether that be known or unknown) the number MUST BE set to the exception's HResult property. Doing so, will set the exit code of the application. Exit codes are used by many applications within the Neo Build Engine process. These codes are also used as an error string ID for exception Message property, to help the user identify the root of the problem. Error string will be prefixed with NB and have a suffix format of {0:d04}, for example: NB1000, NB0101, NB0070. This allows padding of zeros for anything less than 1000.

Module Filename Format

will be defined as NeoBuildErrorCodes.{module}.cs within Neo.Build.Core library. For example: NeoBuildErrorCodes.Wallet.cs file would hold all the error codes for the wallet module. See What is a Module for more details.

What is a Module

refers to the part of code doing the processing within the Neo Build Engine for example, NeoBuildEngine::Wallet:Open(). Wallet is the module. Each class SHOULD BE considered it's own module. Each subclass in the module class that has private or internal WILL NOT be considered a different module for example, NeoBuildEngine::Wallet::Cache:AddItem().

How to Define Module Base

Each module within Neo Build Engine has it own base error number. These modules can hold up to 1000 known errors each. The formula for calculating an error module's base is mb = b * (n + 1); build engine's module base number (b) times number (n) of modules plus one (1) equals module base (mb).

Factors

1. MUST define a unique module base.
2. MUST define a module base between 1000 to 9999.
3. MUST define no more than 1000 error codes for one module.
4. MUST set HResult property in System.Exception with error code number.
5. MUST set Message property in System.Exception with root cause of the error.

Example

// Base
private const int EngineBase = 1;

// Module 1
private const int ModuleBase = Base * 1000;     // 1000
public const int Exception1 = ModuleBase + 1;   // 1001
public const int Exception2 = ModuleBase + 2;   // 1002

// Module 2
private const int ModuleBase = Base * 2000;     // 2000
public const int Exception1 = ModuleBase + 1;   // 2001
public const int Exception2 = ModuleBase + 2;   // 2002

Type of change

• Optimization (the change is only an optimization)
• Style (the change is only a code style for better maintenance or standard purpose)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules