|
| 1 | +--- |
| 2 | +sidebar_position: 4 |
| 3 | +--- |
| 4 | + |
| 5 | +# C# Client Library |
| 6 | + |
| 7 | +This document outlines the designs behind the GSF Carbon Aware C# Client |
| 8 | +Library. |
| 9 | + |
| 10 | +## Namespace |
| 11 | + |
| 12 | +Given the fact this is going to be a library exposing functionality to |
| 13 | +consumers, will use the |
| 14 | +[standard](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-namespaces) |
| 15 | +namespace naming schema: |
| 16 | +`<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]`. For GSF |
| 17 | +CarbonAware SDK this the following schema: |
| 18 | + |
| 19 | +- **Company**: **_GSF_** |
| 20 | +- **Product**: **_CarbonAware_** |
| 21 | +- **Feature**: **_Models_**, **_Handlers_**, ... |
| 22 | + |
| 23 | +An example of a namespace would be: `namespace GSF.CarbonAware.Models` and a |
| 24 | +class (record, interface, ...) that belongs to that namespace would be: |
| 25 | + |
| 26 | +```c# |
| 27 | +namespace GSF.CarbonAware.Models; |
| 28 | + |
| 29 | +public record EmissionsData |
| 30 | +{ |
| 31 | + .... |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +The following namespaces are included: |
| 36 | + |
| 37 | +| namespace | |
| 38 | +| ----------------------------- | |
| 39 | +| GSF.CarbonAware.Exceptions | |
| 40 | +| GSF.CarbonAware.Configuration | |
| 41 | +| GSF.CarbonAware.Handlers | |
| 42 | +| GSF.CarbonAware.Models | |
| 43 | +| GSF.CarbonAware.Parameters | |
| 44 | + |
| 45 | +## Features |
| 46 | + |
| 47 | +### Models |
| 48 | + |
| 49 | +There are two main classes that represents the data fetched from the data |
| 50 | +sources (i.e `Static Json`, [WattTime](https://www.watttime.org), |
| 51 | +[ElectricityMaps](https://www.electricitymaps.com), and |
| 52 | +[ElectricityMapsFree](https://www.co2signal.com/)): |
| 53 | + |
| 54 | +- `EmissionsData` |
| 55 | +- `EmissionsForecast` |
| 56 | + |
| 57 | +A record is defined for each of these data types owned by the library. |
| 58 | + |
| 59 | +```c# |
| 60 | +namespace GSF.CarbonAware.Models; |
| 61 | +public record EmissionsData |
| 62 | +{ |
| 63 | + string Location |
| 64 | + DateTimeOffset Time |
| 65 | + double Rating |
| 66 | + TimeSpan Duration |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +```c# |
| 71 | +namespace GSF.CarbonAware.Models; |
| 72 | +public record EmissionsForecast |
| 73 | +{ |
| 74 | + DateTimeOffset RequestedAt |
| 75 | + DateTimeOffset GeneratedAt |
| 76 | + IEnumerable<EmissionsData> EmissionsDataPoints |
| 77 | + IEnumerable<EmissionsData> OptimalDataPoints |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +The user can expect to either have a primitive type (such as an int) or one of |
| 82 | +these specific models as a return type of the **Handlers**. |
| 83 | + |
| 84 | +### Handlers |
| 85 | + |
| 86 | +There will be two handlers for each of the data types returned: |
| 87 | + |
| 88 | +- `EmissionsHandler` |
| 89 | +- `ForecastHandler` |
| 90 | + |
| 91 | +Each is responsible for interacting on its own domain. For instance, |
| 92 | +EmissionsHandler can have a method `GetAverageCarbonIntensityAsync()` to pull |
| 93 | +EmissionsData data from a configured data source and calculate the average |
| 94 | +carbon intensity. ForecastHandler can have a method `GetCurrentAsync()`, that |
| 95 | +will return a EmissionsForecast instance. (**Note**: The current core |
| 96 | +implementation is using async/await paradigm, which would be the default for |
| 97 | +library too). |
| 98 | + |
| 99 | +In addition, there is a `LocationHandler` that is responsible for retrieving all |
| 100 | +the locations supported by the underlying datasource. |
| 101 | + |
| 102 | +### Parameters |
| 103 | + |
| 104 | +Both handlers require that exact fields be passed in as input. Within the docs |
| 105 | +of each library function, we specifically call out which fields the function |
| 106 | +expects to be defined versus which are optional. Internally, we handle creating |
| 107 | +the CarbonAwareParameters object and validating the fields through that. |
| 108 | + |
| 109 | +## Carbon Aware Parameters |
| 110 | + |
| 111 | +The `CarbonAwareParameters` class allows the user to pass in a unique parameter |
| 112 | +instance to the public methods in the Handlers with the specific parameters |
| 113 | +needed by that call. The list of allowed parameters is defined in the class and |
| 114 | +includes |
| 115 | + |
| 116 | +- SingleLocation |
| 117 | +- MultipleLocations |
| 118 | +- Start |
| 119 | +- End |
| 120 | +- RequestedAt |
| 121 | +- Duration |
| 122 | + |
| 123 | +### Parameter Display Names |
| 124 | + |
| 125 | +The display name of each parameter can be overriden using the public setter. By |
| 126 | +default, each parameter display name is set to the variable name (ex: |
| 127 | +`Start = "start"`). The parameter display names are used when creating the |
| 128 | +validation error messages. Overriding them is useful in situations where the |
| 129 | +variables the user is using for input don't exactly match the default display |
| 130 | +name of the parameter (e.g. the user variable in the controller is |
| 131 | +`periodStartTime` instead of `startTime`). That way, when the error is thrown to |
| 132 | +the user, the parameter names will match the users' expectation |
| 133 | + |
| 134 | +To do the override, define a class that inherits from |
| 135 | +CarbonAwareParametersBaseDTO and uses the [FromQuery(Name = |
| 136 | +"myAwesomeDisplayName")] or [JsonPropertyName("myAwesomeDisplayName")] |
| 137 | +attribute. A second (less recommended) option is to pass the optional arg |
| 138 | +Dictionary<string, string>? displayNameMap when you are directly creating the |
| 139 | +object. With either option, the SDK handles updating references internally. |
| 140 | + |
| 141 | +### Required Properties |
| 142 | + |
| 143 | +The first core check the parameters class does is validating that required |
| 144 | +parameters are defined. By default, all parameters are considered optional. |
| 145 | +Calling the `SetRequiredProperties(...)` function with the desired arguments |
| 146 | +sets the required parameters for the instance. |
| 147 | + |
| 148 | +```csharp |
| 149 | + /// <summary> |
| 150 | + /// Accepts any PropertyNames as arguments and sets the associated property as required for validation. |
| 151 | + /// </summary> |
| 152 | + public void SetRequiredProperties(params PropertyName[] requiredProperties) |
| 153 | +``` |
| 154 | + |
| 155 | +### Validations |
| 156 | + |
| 157 | +The second core check the parameters class does is enforcing validations on the |
| 158 | +parameters themselves. Some common examples include |
| 159 | + |
| 160 | +- Relationship validations: _`start < end` must be true_ |
| 161 | +- Content validations: _`list.Any()` must be true for list fields_ |
| 162 | + |
| 163 | +Calling the `SetValidations(...)` function with the desired arguments sets the |
| 164 | +validations for the instance. |
| 165 | + |
| 166 | +```csharp |
| 167 | + /// <summary> |
| 168 | + /// Accepts any ValidationName as arguments and sets the associated validation to check. |
| 169 | + /// </summary> |
| 170 | + public void SetValidations(params ValidationName[] validationNames) |
| 171 | +``` |
| 172 | + |
| 173 | +### Validate |
| 174 | + |
| 175 | +Calling the `Validate(...)` function validates (1) required parameters and (2) |
| 176 | +specified validations. Currently, the only validation we check is whether |
| 177 | +`start` is before `end`. |
| 178 | + |
| 179 | +If no errors are thrown, the function simply returns. If any validation errors |
| 180 | +are found, they are packaged into a single `ArgumentException` error with each |
| 181 | +being part of the `data` dictionary. |
| 182 | + |
| 183 | +``` |
| 184 | + /// <summary> |
| 185 | + /// Validates the properties and relationships between properties. Any validation errors found are packaged into an |
| 186 | + /// ArgumentException and thrown. If there are no errors, simply returns void. |
| 187 | + /// </summary> |
| 188 | + public void Validate() |
| 189 | +``` |
| 190 | + |
| 191 | +### Getters With Default Fallbacks |
| 192 | + |
| 193 | +Certain parameters have special getters that allow you to define a fallback |
| 194 | +default value if the parameter is null. This can be useful in cases where a |
| 195 | +parameter is optional, so you want to get it if it was defined by the user, or |
| 196 | +otherwise fallback to a specific default. These include `Start`, `End`, |
| 197 | +`Requested`,and `Duration` |
| 198 | + |
| 199 | +``` |
| 200 | + DateTimeOffset StartOrDefault(DateTimeOffset defaultStart) |
| 201 | + DateTimeOffset EndOrDefault(DateTimeOffset defaultEnd) |
| 202 | + DateTimeOffset RequestedOrDefault(DateTimeOffset defaultRequested) |
| 203 | + TimeSpan DurationOrDefault |
| 204 | + |
| 205 | +``` |
| 206 | + |
| 207 | +### Error Handling |
| 208 | + |
| 209 | +The `CarbonAwareException` class is used to report errors to the consumer. It |
| 210 | +follows the `Exception` class approach, where messages and details are provided |
| 211 | +as part of error reporting. |
| 212 | + |
| 213 | +## References |
| 214 | + |
| 215 | +<https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/> |
0 commit comments