microsoft · juzuluag · Dec 14, 2022
@@ -17,6 +17,7 @@ The CLI exposes the primary `getEmissionsByLocationsAndTime` SDK methods via com
         - [Single Location Emissions](#single-location-emissions)
         - [Multiple Location Emissions](#multiple-location-emissions)
         - [Emissions with Start and End Times](#emissions-with-start-and-end-times)
+        - [Emissions Locations](#emissions-locations)
 
 ## Build and Install
 
@@ -37,7 +38,7 @@ dotnet publish ./src/CarbonAware.CLI/src/CarbonAware.CLI.csproj -c Release -o <y
 To use the CLI for the first time, navigate to your installation directory and run the binary with the `-h` flag to see the help menu.
 
 On Windows: `.\caw.exe -h`
-On MacOS/Linux: `.\caw -h`
+On MacOS/Linux: `./caw -h`
 
 ### emissions
 
@@ -364,3 +365,26 @@ output:
   ]
 }]
 ```
+
+##### Emissions Locations
+
+command: `.\caw locations`
+
+output:
+
+```json
+{
+  "eastus": {
+    "Latitude": 37.3719,
+    "Longitude": -79.8164,
+    "Name": "eastus"
+  },
+  ...
+  "switzerlandnorth":{
+    "Latitude": 47.451542,
+    "Longitude": 8.564572,
+    "Name": "switzerlandnorth"
+  },
+  ...
+}
+```
@@ -18,6 +18,7 @@ The WebApi replicates the CLI and SDK functionality, leveraging the same configu
     - [POST emissions/forecasts/batch](#post-emissionsforecastsbatch)
     - [GET emissions/average-carbon-intensity](#get-emissionsaverage-carbon-intensity)
     - [POST emissions/average-carbon-intensity/batch](#post-emissionsaverage-carbon-intensitybatch)
+    - [GET emissions/locations](#get-emissionslocations)
   - [Error Handling](#error-handling)
   - [Autogenerate WebAPI](#autogenerate-webapi)
   - [Data Sources](#data-sources)
@@ -316,6 +317,49 @@ The response is an array of CarbonIntensityDTO objects which each have a locatio
 ]
 ```
 
+### GET emissions/locations
+
+This endpoint lists all the supported locations that the datasources potentially can have access to. This information is coming from the `location-source/json` files, that contain dictionaries in the form of <A Location key name, GeoCoordinates>, for instance:
+
+```json
+{
+  "eastus": {
+    "Latitude": 37.3719,
+    "Longitude": -79.8164,
+    "Name": "eastus"
+  },
+  ...
+  "switzerlandnorth":{
+    "Latitude": 47.451542,
+    "Longitude": 8.564572,
+    "Name": "switzerlandnorth"
+  }
+}
+```
+
+`Emissions` and `Forecasts` endpoints would use the location's `key` name returned by the `emssions/locations` endpoint.
+
+**Note**: If there is ***a location key name*** collision while loading two or more location json files and there is no `LocationDataSourcesConfiguration` `Prefix` and/or `Delimiter` settings, the system would change the collision key name by appending an underscore character and a sequence number to it (i.e. `<key name>`***_seqnumber***). For instance two location json files having `swedencentral` as key, after loading, it would become:
+
+```json
+{
+  "swedencentral": {
+    "Latitude": 60.67488,
+    "Longitude": 17.14127,
+    "Name":"swedencentral"
+  },
+  ...
+  "swedencentral_1": { // key collision. key renamed.
+    "Latitude": null,
+    "Longitude": null,
+    "Name": "SE"
+  },
+  ...
+}
+```
+
+If there is a third file with the same key name, it would be `swedencentral_2` and so on. This information is not persisted, but now the user can make requests using `swedencentral` and/or `swedencentral_1`.
+
 ## Error Handling
 
 The WebAPI leveraged the [.Net controller filter pipeline](https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-6.0) to ensure that all requests respond with a consistent JSON schema.

@@ -25,6 +25,12 @@
 var parsedStart = DateTimeOffset.Parse(startDate);
 var parsedEnd = DateTimeOffset.Parse(endDate);
 
+// Locations
+var locationHandler = serviceProvider.GetRequiredService<ILocationHandler>();
+var locations = await locationHandler.GetLocationsAsync();
+var value = locations[location];
+Console.WriteLine($"Details for {location}: {value}");
+
 // EmissionsData
 var emissionsDataResult = await handlerEmissions.GetEmissionsDataAsync(location, parsedStart, parsedEnd);
 var rating = emissionsDataResult.First().Rating;

@@ -20,6 +20,7 @@
   <ItemGroup>
     <ProjectReference Include="..\..\CarbonAware\src\CarbonAware.csproj" />
     <ProjectReference Include="..\..\CarbonAware.Aggregators\src\CarbonAware.Aggregators.csproj" />
+    <ProjectReference Include="..\..\CarbonAware.LocationSources\src\CarbonAware.LocationSources.csproj" />
   </ItemGroup>
 
   <ItemGroup>
@@ -33,6 +34,11 @@
       <AutoGen>True</AutoGen>
       <DependentUpon>LocalizableStrings.resx</DependentUpon>
     </Compile>
+    <Compile Update="Commands\Location\LocalizableStrings.Designer.cs">
+      <DesignTime>True</DesignTime>
+      <AutoGen>True</AutoGen>
+      <DependentUpon>LocalizableStrings.resx</DependentUpon>
+    </Compile>
     <Compile Update="Common\CommonLocalizableStrings.Designer.cs">
       <DesignTime>True</DesignTime>
       <AutoGen>True</AutoGen>
@@ -49,6 +55,10 @@
       <Generator>ResXFileCodeGenerator</Generator>
       <LastGenOutput>LocalizableStrings.Designer.cs</LastGenOutput>
     </EmbeddedResource>
+    <EmbeddedResource Update="Commands\Location\LocalizableStrings.resx">
+      <Generator>ResXFileCodeGenerator</Generator>
+      <LastGenOutput>LocalizableStrings.Designer.cs</LastGenOutput>
+    </EmbeddedResource>
     <EmbeddedResource Update="Common\CommonLocalizableStrings.resx">
       <Generator>ResXFileCodeGenerator</Generator>
       <LastGenOutput>CommonLocalizableStrings.Designer.cs</LastGenOutput>

@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="utf-8"?>
+<root>
+  <!-- 
+    Microsoft ResX Schema 
+
+    Version 2.0
+
+    The primary goals of this format is to allow a simple XML format 
+    that is mostly human readable. The generation and parsing of the 
+    various data types are done through the TypeConverter classes 
+    associated with the data types.
+
+    Example:
+
+    ... ado.net/XML headers & schema ...
+    <resheader name="resmimetype">text/microsoft-resx</resheader>
+    <resheader name="version">2.0</resheader>
+    <resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader>
+    <resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader>
+    <data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data>
+    <data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data>
+    <data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64">
+        <value>[base64 mime encoded serialized .NET Framework object]</value>
+    </data>
+    <data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64">
+        <value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
+        <comment>This is a comment</comment>
+    </data>
+
+    There are any number of "resheader" rows that contain simple 
+    name/value pairs.
+
+    Each data row contains a name, and value. The row also contains a 
+    type or mimetype. Type corresponds to a .NET class that support 
+    text/value conversion through the TypeConverter architecture. 
+    Classes that don't support this are serialized and stored with the 
+    mimetype set.
+
+    The mimetype is used for serialized objects, and tells the 
+    ResXResourceReader how to depersist the object. This is currently not 
+    extensible. For a given mimetype the value must be set accordingly:
+
+    Note - application/x-microsoft.net.object.binary.base64 is the format 
+    that the ResXResourceWriter will generate, however the reader can 
+    read any of the formats listed below.
+
+    mimetype: application/x-microsoft.net.object.binary.base64
+    value   : The object must be serialized with 
+            : System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
+            : and then encoded with base64 encoding.
+
+    mimetype: application/x-microsoft.net.object.soap.base64
+    value   : The object must be serialized with 
+            : System.Runtime.Serialization.Formatters.Soap.SoapFormatter
+            : and then encoded with base64 encoding.
+
+    mimetype: application/x-microsoft.net.object.bytearray.base64
+    value   : The object must be serialized into a byte array 
+            : using a System.ComponentModel.TypeConverter
+            : and then encoded with base64 encoding.
+    -->
+  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
+    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
+    <xsd:element name="root" msdata:IsDataSet="true">
+      <xsd:complexType>
+        <xsd:choice maxOccurs="unbounded">
+          <xsd:element name="metadata">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" />
+              </xsd:sequence>
+              <xsd:attribute name="name" use="required" type="xsd:string" />
+              <xsd:attribute name="type" type="xsd:string" />
+              <xsd:attribute name="mimetype" type="xsd:string" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="assembly">
+            <xsd:complexType>
+              <xsd:attribute name="alias" type="xsd:string" />
+              <xsd:attribute name="name" type="xsd:string" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="data">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
+              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
+              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="resheader">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" />
+            </xsd:complexType>
+          </xsd:element>
+        </xsd:choice>
+      </xsd:complexType>
+    </xsd:element>
+  </xsd:schema>
+  <resheader name="resmimetype">
+    <value>text/microsoft-resx</value>
+  </resheader>
+  <resheader name="version">
+    <value>2.0</value>
+  </resheader>
+  <resheader name="reader">
+    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <resheader name="writer">
+    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <data name="LocationsCommandDescription" xml:space="preserve">
+    <value>Returns all the supported locations </value>
+  </data>
+</root>
@@ -0,0 +1,25 @@
+using CarbonAware.Interfaces;
+using System.CommandLine;
+using System.CommandLine.Invocation;
+using System.Text.Json;
+
+namespace CarbonAware.CLI.Commands.Location;
+
+public class LocationsCommand : Command
+{
+    public LocationsCommand() : base("locations", LocalizableStrings.LocationsCommandDescription)
+    {
+        this.SetHandler(this.Run);
+    }
+
+    internal async Task Run(InvocationContext context)
+    {
+        var serviceProvider = context.BindingContext.GetService(typeof(IServiceProvider)) as IServiceProvider ?? throw new NullReferenceException("ServiceProvider not found");
+        var locationSource = serviceProvider.GetService(typeof(ILocationSource)) as ILocationSource ?? throw new NullReferenceException("ILocationSource not found");
+
+        var locations = await locationSource.GetGeopositionLocationsAsync();
+        var serializedOuput = JsonSerializer.Serialize(locations);
+        context.Console.WriteLine(serializedOuput);
+        context.ExitCode = 0;
+    }
+}
@@ -11,6 +11,7 @@
 using System.CommandLine;
 using System.CommandLine.Builder;
 using System.CommandLine.Parsing;
+using CarbonAware.CLI.Commands.Location;
 
 var config = new ConfigurationBuilder()
     .UseCarbonAwareDefaults()
@@ -36,6 +37,7 @@
 var rootCommand = new RootCommand(description: CommonLocalizableStrings.RootCommandDescription);
 rootCommand.AddCommand(new EmissionsCommand());
 rootCommand.AddCommand(new EmissionsForecastsCommand());
+rootCommand.AddCommand(new LocationsCommand());
 
 var parser = new CommandLineBuilder(rootCommand)
     .UseDefaults()