Setting up a GeRes2 Development Environment for local debugging

Setting up a development and production environment is very similar. We start with the easier one which is setting up GeRes2 for development on your local Machine. Please check our requirements-page for details on pre-requisites you need to get started for development.

Some of the steps described above are described at a greater level of detail in separate wiki-pages. These are listed at the end of this article.

  1. Create a Service Bus Namespace in the Microsoft Azure Management Portal.
    Since for local debugging we can use the storage emulator shipping with the Microsoft Azure SDK for storage services you don’t need to create storage accounts just for local development/debugging. Nevertheless, you need to create a Service Bus Namespace in the Azure Management Portal.
    1. Note: the SDK library versions we used for GeRes2 development currently do not work with Service Bus 1.1. for Windows Server. Therefore running Service Bus in the public Cloud Microsoft Azure is also required for local debugging.
    2. We will investigate with future releases to update GeRes2 so that it is also compatible with the Windows Azure Pack for Windows Server and thus Service Bus for Windows Server what would enable GeRes2 to run in private clouds, as well.
  2. Configure Microsoft Azure Active Directory in the Azure Management Portal.
    GeRes2 leverages Azure Active Directory to prevent unauthorized callers from making use of the GeRes2 WebAPIs. It makes use of the most simple way of authentication and authorization through service credentials, by default. That means you need to perform the steps below.

    Note:further details for those including screenshots can be found in the wiki-page “Configuring Azure Active Directory for GeRes2”.
    1. Create am Azure AD if you don’t have one, yet. Since every Azure subscription gets one directory, by default, you can make use of this one if appropriate for you instead of creating a new one.
    2. Register the GeRes2 JobHub as an application of type WebAPI in your Azure Active Directory.
      1. Take a note of the “APP ID URI” setting you have selected as you need to update the GeRes2 configuration based on it later in the process.
    3. Register a service-application that consumes the GeRes2 JobHub. Note that when writing this documentation, you need to register service applications as “Web API” in Azure AD, as well. This UI might be updated in the future to reflect a better wording for service applications, in general, in the future.
      1. After created, navigate to the Configuration-page of this newly created service application.
      2. Take a note of the ClientID since you need it later for configuring GeRes2 clients such as the included sample console.
      3. Generate a new secret key and take immediate note of it since you need it later for configuring GeRes2 clients such as the included sample console.
    4. Finally add a permission to Azure AD that enables the service-application created in step 3 above to call the web API in step 2 above. At the time of writing this documentation, this was only possible through http://graphexplorer.cloudapp.net or by using the graph API of Azure Active Directory, directly.
  3. Clone the GeRes2 Codeplex repository to your local machine using git.
    1. Example: git clone https://git01.codeplex.com/geres2
  4. Open Visual Studio as an administrator and then open the solution GeRes2.sln in Visual Studio.
    1. Before building, right-click the top-level solution in the Visual Studio solution explorer and select “Manage NuGet Packages for Solution”.
      image_thumb[6]
    2. In the NuGet package manager dialog, select “Restore” at the very top of the window. This will restore all NuGet packages required for successfully compiling GeRes2. Do this before you do your first build since we use portable libraries that are partially dependent on build-tasks downloaded with those NuGet packages. If you don’t do this upfront, your first build will fail and you’ll need to do a second build that will then succeed.
      image_thumb[5]
    3. After you’ve downloaded the NuGet-packages you can completely re-build the solution – it should immediately succeed with those actions being taken assuming you have all pre-requisites installed on you machine
  5. Update the Service Bus connection strings.
    To get a working version of GeRes2 you now need to update the Azure service configuration file in the Geres2_Cloud Microsoft Azure deployment project. Open the file ServiceConfiguration.Local.cscfg in the project GeRes2_Cloud and update the following configuration settings with the ServiceBus connection string copied from the Azure management portal.
    1. The configuration setting you need to update is called “Geres.Messaging.ServiceBusConnectionString”.
    2. You need to update this specific setting to match your Service Bus connection string copied from the management portal for for all three roles, Geres.Azure.PaaS.JobProcessor, Geres.Azure.PaaS.JobHub and Geres.Azure.PaaS.AutoScaler.
  6. Update the configuration settings related to Azure Active Directory in the GeRes2 backend.
    Open the file ServiceConfiguration.Local.cscfg in the project GeRes2_Cloud and update the following configuration settings depending on the information you’ve written down from step 2 above:
    1. Geres.Security.AzureAdTenant = <yourazureadname>.onmicrosoft.com
    2. Geres.Security.AzureAdAudienceUri = <your APP ID URI> you have configured as part of step 2.2 above.
  7. (optional) Deploy the sample jobs to test your configuration.
    GeRes2 ships with a set of sample jobs which you can deploy to get started quickly and test your configuration. In the case of local debugging, you need to perform the following steps below to deploy the sample jobs.
    1. Re-build the complete solution.
    2. Navigate to the directory in your GeRes2 local git repository: .\geres2\jobs\SampleTenant\GeresJobSamples
    3. Create a ZIP archive with the contents of this folder (directly in the root of the ZIP) called geresjobsamples.zip.
    4. Create a container in the Azure emulator development storage (e.g. using a tool such as CloudBerry Labs Storage Explorer) called jobprocessorfiles.
    5. Copy that ZIP-file in a local folder called “SampleTenant”.
    6. Upload that folder “SampleTenant” with the ZIP-package in the jobprocessorfiles container so that the resulting BLOB-name of the geresjobsamples.zip file relative to the root of the storage emulator blob storage service URL is /jobprocessorfiles/SampleTenant/geresjobsamples.zip.
    7. Note: the names are case-sensitive, especially “SampleTenant” in the URL above.
    8. Note: CloudBerry Labs Storage Explorer is one of the tools making it very easy to create the directory structures as mentioned above.
  8. (optional) Configure the GeresJobRequestorSampleConsole app.config configuration settings to reflect the appropriate authentication information for Azure AD as configured in step 2 earlier:
    1. Update the setting “WindowsAzureADTenant” to reflect your Azure Active Directory tenant, e.g. https://login.windows.net/yourazureadtenant.onmicrosoft.com where yourazureadtenant is the name of the AD created/configured in step 2 earlier.
    2. Update the setting “WindowsAzureAdGeresWebApiId” with the APP ID URI as configured and written down in step 2.2 earlier.
    3. Update the setting “ClientId” with the ClientID as taken note from in step 2.3.2 earlier.
    4. Update the setting “ClientSecret” with the secret key as created and written down in step 2.3.3 earlier.
  9. Set Geres2_Cloud as startup project and run the solution in Visual Studio.
  10. In the running instance of Visual Studio, right-click the project GeresJobRequestorSampleConsole in the solution and select “Debug – Start new Instance” from the context menu.
  11. After the console app started, enter the following data to schedule jobs on input request from the console app:
    1. Enter “s” for submitting jobs.
    2. Enter “SampleTenant” as TenantId – this needs to match the folder in the jobprocessorfiles-container that contains the ZIP-file with the job-binaries as done in step 7 earlier.
    3. Select either “f” for the simpler FinancialYearEnd job or “u” for the more complex UpdateWaitPostings job. More details are available in the section “Implementing Jobs and Job-Samples for GeRes2”.
    4. Select “s” for single operations (this is simpler for getting started).
    5. Enter the number of jobs you want to execute.
    6. Select “y” for running against the local emulator.
  12. After that you should see the steps executed in the sample console application. It starts by authenticating against Azure AD, then submits jobs against the GeRes2 Web API and subscribes to SignalR notification channels.

With that you should have a working demo-deployment of GeRes2 running locally against the emulator. There are several wiki-pages outlining some of the topics mentioned above at a greater level of detail. These are:

Configuring Service Bus for GeRes2

Configuring Storage for GeRes2

Configuring Azure Active Directory for GeRes2

Deploying Jobs for a GeRes2-instance in Blob-storage

Implementing new Jobs to be executed in the GeRes2-framework

Implementing a client to work against the GeRes2 Web API and SignalR API