Overview

This Nuget package contains numerous helper methods and common functionality useful in any application. To install, you can search Nuget for Sphyrnidae.Common - (Gnu General Public License). The source code is open-sourced, and is located in GitHub: https://github.com/dbartels13/Common This documentation will guide you through all of the utilities available in this package.

Quick Start

API Setup: How to setup your API project

Authentication

To learn about the Authentication and Authorization (JWT-based) go here

Utility class types

All of the functionality in this library can be broken down into the following categories:

1. Stand-Alone Helper Methods
2. Interface Driven Functionality
3. Base Classes

4. Api-Specific Behavior

Helper Methods

These methods can be directly called without any interface registration. As such, all customization in the behavior of these methods is done via method overloads. All calls to uses these classes/methods are either extension methods, or at static in nature.

Active Directory: Methods for accessing active directory (not currently supported)

BinaryList: Fast searching of a list

Compression: Shrinking a string (eg. serialized object)

Dynamic Sql: Helper for building a complex sql statement

Extension Methods: All kinds of extension methods

Named Locker: Allows items to be locked on a name instead of the same global object

Path and Url Builder: Methods for building URL's or Paths

Retry: Executes something repeatedly until no exception is thrown

SafeTry: Wrapper around try/catch statements, with some automated exception handling

Serialize: Performs de/serialization of either XML or JSON string/objects

Service Locator: Allows injection of any service by injecting a single service instead

Interface-Based Functionality

These pieces of functionality are abstracted into an interface. From there, a default implementation is usually provided. A mock implementation is also provided. If the default implementation is abstract in nature, there may be a child class which does the rest of the implementation. Lastly, there could be a wrapper class around the interface. This wrapper class is sometimes done for ease-of-use, but is also done if there is specific functionality that should be done for every possible implementation (eg. it wraps the interface call in some helper code)

Functionality	Interface	Mock	Implementation	Wrapper Class	Notes
Alerts	IAlert	AlertNone	Alert
API Responses	IApiResponse	ApiResponseStandard	ApiResponseStandard
Application Settings	IApplicationSettings	ApplicationSettingsMock	None		You must override in your own project
Caching	ICache	CacheNone	CacheLocal CacheDistributed CacheLocalAndDistributed (Default)	Caching
Email	IEmail	EmailMock	EmailMock (Default) DotNetEmail	Email	EmailBase: Content generation
Encryption	IEncryption	EncryptionNone	EncryptionDispatcher (Default) EncryptionStrong EncryptionWeak EncryptionNormal EncryptionOld	EncryptionExtensions	Wrapper class is a string extension method
Environmental Settings	IEnvironmentSettings	EnvironmentalSettingsMock	EnvironmentalSettings	SettingsEnvironmental
Feature Toggles	IFeatureToggleSettings	FeatureToggleSettingsDefault	FeatureToggleSettings	SettingsFeatureToggle	The implementation is an abstract class, so you should provide your own implementation
Http Client	IHttpClientSettings	HttpClientSettingsMock	HttpClientSettings
Http Data	IHttpData	HttpDataMock	HttpData
Identity / Authentication	IIdentityHelper	BasicIdentity	BasicIdentity
Logging	ILogger	NonLogger	Logger
Request Data	IRequestData	RequestDataMock	RequestData
SignalR	ISignalR	SignalRMock	SignalR	SignalRHub
User Preferences	IUserPreferenceSettings	UserPreferenceSettingsDefault	UserPreferenceSettings	SettingsUserPreference	The implementation is an abstract class, so you should provide your own implementation
Variables	IVariableSettings	VariableSettingsDefault	VariableSettings	SettingsVariable	The implementation is an abstract class, so you should provide your own implementation

Base Classes

The following are all base classes available for your consumption. These should always be inherited from because they provide some automatic "wiring" up of things like logging.

It's important to know the naming conventions used for designing your API's. This basically assumes that you have a layered architecture with each layer having a defined responsibility and inputs/outputs. Here are the layers that are portrayed by these base classes:

1. BaseApi [See Api for more information): All controllers should inherit from this class. A controller is solely responsible for retrieval of request objects and populating the response. A controller may be versioned if the request/response structure changes for an endpoint. Any business logic should go in the "Engine" layer.
2. BaseEngine: All engines should inherit from this class. An engine is responsible for performing the main business logic for the API endpoint. There should be a 1:1 mapping between a controller action and an engine method (this could be M:1 with versioning). The engine will work with all the other layers to get data, and then perform the proper business logic to ultimately return a business object back to the controller's action.
3. BaseRepo [See Data Access Layer for more information]: All database repositoris should inherit from this class. A repo is responsible for CRUD operations against a repository (eg. database, file sytem, etc). It is best practice to usually have a repository class per database table.
4. WebServiceBase [See Web Services for more information]: All web services should inherit from this class. A web service is a call to another system (could be SOA, microservices, or an external system). Each system/API that you need to access should be it's own web service class.
5. Service layer (no base class): A service layer is a class that does one of the following things:
   1. Wrapper around a repository class (eg. for caching)
   2. Wrapper around a web service class (eg. for caching or parsing of the response)
   3. Performs common business logic (eg. can be shared across multiple engines)
6. EmailBase: You can inherit from this class to define a system email. This e-mail will be sent to the current user (logged in Identity). You will only need to override the Subject and Content. You may also wish to have inherit and create your own base class which replaces the Shell
7. EncryptionAlgorithm: Any algorithms you wish to register for encryption should inherit from this class. This is only used when using the EncryptionDispatcher implementation of the IEncryption interface. Alternatively, if you develop your own implementation and wish to use this same logic, you could reuse this base class.