Skip to content

Latest commit

 

History

History
51 lines (38 loc) · 4.58 KB

README.md

File metadata and controls

51 lines (38 loc) · 4.58 KB
Raw

License notes

The Azure Batch C# client is now under the MIT license. Prior to March 10 2017 it was under the Apache 2.0 license.

Azure Batch client developer guide

Batch.sln is your one stop shop for all things related to the Azure Batch C# client library. This solution file contains all of the projects affiliated with the Azure Batch client (including testing and tooling).

Changing the Azure Batch client

Depending on the type of change you want to make, the work required varies. If you follow this process you shouldn't miss anything:

  1. Update the Azure Batch Swagger specification, which resides in the Azure/azure-rest-api-specs GitHub repository.
  • Add new entity types into the Swagger specification.
  • Add new APIs as path-verb pairs in the Swagger specification.
  • Add/remove properties on existing entity types in the Swagger specification.
  1. Regenerate the src\GeneratedProtocol folder using the steps below.
  2. Update the convenience layer specification file: Tools\ObjectModelCodeGeneration\ObjectModelCodeGenerator\BatchProperties.json.
  • Add new entities that match the Swagger defined entities.
  • Add/remove properties on existing entities as done in the Swagger specification.
  1. Regenerate the src\Generated folder from the convenience layer specification file using the steps below.
  2. Add any custom code on the Generated objects into partial classes located in the src directory.
  • You might want to do this to add an [Obsolete] attribute or to add some helper factory methods.
  1. If any APIs have changed, or if new APIs have been added, you must update the following places:
  • The src\IProtocolLayer.cs interface.
  • The src\ProtocolLayer.cs class.
  • The corresponding operations class, for example PoolOperations.cs.
  • The corresponding entity which the operation is performed on, for example CloudPool.cs.
  1. Add tests for your new models and APIs into the correct test projects.
  • Azure.Batch.Unit.Tests for unit tests. These tests do not have any external dependencies (they run entirely in-memory) and are used in the continuous integration job to validate checkins.
  • BatchClientIntegrationTests for integration tests. These tests run against a live Azure Batch endpoint and do not run during CI.
  • Note: You should prefer to add unit tests over integration tests where possible -- integration tests should be reserved for ensuring that the Batch Service accepts the Swagger requests. Testing service behavior should occur in a service test, not the client.

The src\GeneratedProtocol folder

The GeneratedProtocol folder holds the code generated by the AutoRest tool from a Swagger specification. In order to regenerate this code, all you need to do is run: RegenerateBatch.cmd <Path to Swagger file>.

You can optionally edit the RegenerateBatch.cmd script to point to a newer version of AutoRest if you would like to take advantage of new AutoRest features.

The src\Generated folder

This folder contains the convenience layer models for Azure Batch. It is generated from a custom tool. The custom tool reads a specification file located here: Tools\ObjectModelCodeGeneration\ObjectModelCodeGenerator\BatchProperties.json. The convenience layer models require more metadata than the Swagger specification provides, so this file is an extra mapping layer on top of Swagger which provides more detail. Note: The BatchProperties.json specification file just contains the entities; it doesn't have anything related to the actual APIs.

  1. New entities defined in the Swagger specification have to be added here as well. See an existing entity for an example.
  2. If the type or name of a property has changed in the underlying Swagger specification, it should be updated here as well.

There are a number of special flags which have meaning in the BatchProperties.json file. The easiest way to see a list of what flags are supported and at what level is to look at the backing code generation code:

  1. For properties: Tools\ObjectModelCodeGeneration\CodeGenerationLibrary\PropertyData.cs
  2. For types: Tools\ObjectModelCodeGeneration\CodeGenerationLibrary\ObjectModelTypeData.cs

Once BatchProperties.json is updated with your changes, mark the ObjectModelCodeGenerator as your startup project in Visual Studio and run it -- it will regenerate the contents of the src\Generated folder.

Impressions