C#Bot File Structure

This article provides a summary of the client-side, server-side, and test target architecture, and briefly explains the organization, importance and usage of the key concepts for each framework.

Language + Framework

C#Bot uses an ASP.NET Core server-side framework which is a cross platform, open-source framework for building web applications. The testing target is also written in C#, and uses both xUnit and Specflow 3. C#Bot also uses React, a javascript library for developing client-side user interfaces.

Server-Side Directory Structure

src
├───Controllers                 API controllers to connect to the client-side
│   └───Entities
├───Exceptions                  Common exceptions that are used
├───Graphql                     All internal GraphQL functions
│   ├───Fields
│   ├───Helpers
│   └───Types
├───Helpers                     Helper classes
├───Migrations                  Database migration scripts
├───Models                      Entities as defined in the entity model
├───Properties                  Server launch properties
├───Security                    Rules defined in the security model
│   └───Acl
├───Services                    Services to be used in DI
│   ├───CertificateProvider     Providers for fetching pfx certs
│   └───Scheduling              Services for scheduled tasks
│       └───Tasks
└───Utility                     Utility classes, often helpers for the request pipeline

Controllers

Controllers are the HTTP/HTTPS endpoints for the application. They reside in the Controllers directory.

A controller will typically follow this structure:

/// <summary>
/// Gets the logged in user
/// </summary>
/// <returns>The current logged in user</returns>
[HttpGet]
[HttpPost]
[Produces("application/json")]
[Route("me")]
[Authorize]
public async Task<UserResult> Get()
{
    var user = await _userService.GetUser(User);
    return user;
}

The [HttpGet] and [HttpPost] attributes specify that this endpoint will take requests from both GET and POST HTTP requests.

The [Produces("application/json")] attribute specifies that any data returned by this endpoint will be serialized into JSON before returning to the client.

The [Route("me")] attribute specifies that the endpoint is located at /me in the URL. Please note that this is relative to the URL of the controller, so if the controller was specified to exist at /account, the endpoint would be at /account/me.

The [Authorize] attribute requires the endpoint to have an authorized user, with authorization being enforced by the 'default authorization policy' found in Startup.cs. By default, users are authenticated against either a Bearer or Cookie authentication scheme.

Server-Side Models

Server-Side models are defined as C# classes inside of the Models directory. Each model is a plain C# class with all of the entities attributes, which are defined in the entity model. In addition, there is also a property called Acls which implements security rules which are defined by the security model. These classes are coupled with both a configuration and a type file. The configuration file configures the entity in the database, whereas the type file defines type mappings for GraphQL.

GraphQL

The Graphql folder contains the GraphQL queries, mutations and any helpers required to execute the various GraphQL functions. For each entity defined in the entity model there are functions created to provide the full CRUD functionality.

Security

The security folder contains the rules defined in the security model and helper classes associated with these security rules. It is important to note that the ACL folder contains classes which can be altered to contain custom security logic.

Services

This folder contains the services added to the server-side via dependency injection. These services make the bulk of the application logic in a C#Bot project.

Client-Side Directory Structure

src
├───Assets           Static assets that are needed in React (eg. images)
├───Models
│   ├───Entities     The models that are defined in the entity model
│   └───Security     The rules that are defined in the security model
│       └───Acl
├───scss
│   ├───abstracts    Abstract styles (eg. colour variables)
│   ├───components   Styles for individual components
│   ├───elements     Styles for individual elements
│   └───pages        Styles for specific pages in the application
├───Services         Any services that are required in the application
├───Util             A collection of utility functions
├───Validators       Client-Side validators for validating models against
└───Views
    ├───Components   All the components that are used by the client-side
    ├───Pages        Pages that are placed on the UI model
    │   └───Admin    Admin pages for the backend views
    └───Tiles        Tiles that are placed on the UI model

Views

When writing a custom feature inside of a ReactBot view protected region, the first place to look at will be the src/Views/Pages directory. Any pages placed on the UI model will be output here, with routing configured to render the page.

In ReactBot, all React components are class-based components by convention. This allows cleaner integration with MobX using the decorator syntax. However, there is no restriction on this and components can be function-based components if desired.

It is important when writing pages, or any other custom UI elements, that components are declared as MobX Observers. If this is not done, then there can be issues with elements not re-rendering on state changes.

Models

The client-side models are the javascript versions of the entities which were defined in the entity diagram. These contain observable attributes identical to those in the entity diagram. There are a series of helper methods on these models for fetching and persisting data to and from the server-side via the GraphQL API.

Test Target Directory Structure

testtarget
├───Selenium                        Includes the entirety of the selenium testing target
│   ├───Factories                   Selenium Based factories
│   ├───PageObjects                 Includes all page object models
│   │   ├───CRUDPageObject
│   │   │   └───PageDetails
│   │   ├───LoginPageObject
│   │   ├───LogoutPageObject
│   ├───Setup                       Startup configuration for Selenium tests
│   ├───Steps
│   │   ├───BotWritten              Includes any bot written step definitions
│   ├───Tests
│   │   ├───BotWritten              Includes any bot written tests
│   │   │   ├───Admin
│   │   │   ├───BulkOptions
│   │   │   ├───Checkbox
│   │   │   ├───Crud
│   │   │   │   ├───CreateTests
│   │   │   │   └───DeleteTests
│   │   │   ├───Login
│   │   │   ├───Navigation
│   │   │   ├───Pagination
│   │   │   ├───Search
│   │   │   ├───UnauthorizedLoginRedirect
│   │   │   └───Validator
│   └───Utils                       Selenium Utils
└───Serverside                      Includes the server-side API and unit tests
    ├───EntityObjects
    │   ├───BaseChoice              Includes all base choice invalid/valid helper methods
    │   └───Models                  Includes entities for the test target
    ├───Properties
    ├───Settings
    ├───Setup                       Startup methods for server-side tests
    ├───Tests
    │   └───botwritten              Bot written server-side tests
    └───Utils                       Helper methods for server-side tests

Selenium Test Target

The Selenium test target is composed entirely of Selenium tests, helper methods and page object models of the applications client-side.

Server-Side Test Target

The server-side test target includes all of the API and unit tests coupled with the C#Bot application. Any resources which are shared between the testing targets are included in this project. This includes BaseChoice, entity models, test configuration and several helper methods for creating and manipulating data.

Setup and Running

C# Local Environment Setup

Build

In order to produce a production build of the application, first you must open a terminal in the serverside/src directory of the application and run dotnet publish -c Release.
This will create a release build of the server and client applications, and bundle them together. The output of the build is stored in serverside/src/bin/Release/netcoreapp2.2/publish, which can be then deployed on any server.

It is important to note that even though there is a file called Properties/launchSettings.json it will not configure the release build of the application, it is only used for configuration of IDE's. When deploying a production build, any server settings must be configured using the specific tools provided by the web server of choice (eg. web.config for IIS or nginx.config NGINX).