Home

Awesome

Build status

Microsoft Graph SDK Code Generator

Source code writers for VIPR utilizing T4 templates. The GraphODataTemplateWriter receives an OdcmModel from VIPR and uses it to fill in a T4 template located within this repository.

Currently the following target languages are supported by this writer:

Contents

Prerequisites

Getting started

This project uses git submodules to integrate upstream dependencies, specifically Vipr. If you need an alternate branch to include special fixes you'll need to check that out manually within the submodule.

For the solution to open properly, ensure submodules are updated before opening it in Visual Studio. When initially cloning this repo, use git clone --recursive to update submodules at the same time. Later, run git submodule update to manually update submodules. If you don't use the --recursive switch when cloning, run git submodule init first to initialize the submodule.

Once setup is complete, you can work with the GraphODataTemplateWriter solution as usual. If you encounter problems, make sure NuGet packages and project references are all up-to-date.

For more information on submodules read this chapter from the Git book and search the Web.

Using Typewriter

Typewriter is a new solution for generating code files using the GraphODataTemplateWriter and VIPR. It is an executable that is intended to simplify the generation of code files. Build the solution to find the typewriter executable in \MSGraph-SDK-Code-Generator\src\Typewriter\bin\Release. The typewriter run options are:

Example typewriter usage

Transform metadata with XSLT.

The output cleanMetadata.xml will be located in the same directory as typewriter.exe.

.\typewriter.exe -v Info -m https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/v1.0_metadata.xml -g Transform -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl

Transform metadata with XSLT and add documentation annotations.

The output cleanMetadataWithDescriptionsv1.0.xml will be located in the same directory as typewriter.exe.

.\typewriter.exe -v Info -m https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/v1.0_metadata.xml -g TransformWithDocs -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl -d D:\repos\microsoft-graph-docs

Generate TypeScript typings from a CSDL (metadata) file without cleaning or annotating the CSDL.

The output will go in to the outputTypeScript directory.

.\typewriter.exe -v Info -m D:\cleanMetadataWithDescriptions_v10.xml -o outputTypeScript -l TypeScript -g Files

Clean and annotate a metadata file with documentation annotations sourced from the documentation repo

The output metadata file will go in to the output2 directory. The output metadata file will be named cleanMetadataWithDescriptionsv1.0.xml based on the default values.

.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output2 -d D:\repos\microsoft-graph-docs -g Metadata

Generate C# code files from the metadata that will be cleaned and annotated with documentation annotations sourced from the documentation repo

The output C# code files will go in to the output directory.

.\typewriter.exe -v Info -m D:\v1.0_2018_10_23_source.xml -o output -l TypeScript -d D:\repos\microsoft-graph-docs -g Full

Use/debug Typewriter in VSCode

Use Typewriter to test your beta metadata

We assume that the metadata you are using is based off the beta metadata file.

  1. Download the latest Typewriter release.
  2. Run Typewriter to generate a clean metadata file from your test metadata file. The output file will be cleanMetadata.xml.

.\typewriter.exe -v Info -m <TODO-SET-PATH-TO-YOUR-METADATA> -g Transform -t https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/transforms/csdl/preprocess_csdl.xsl

<!-- Excludes documentation which would make for an ugly diff. May need to add the doc step for diff purposes. -->
  1. Generate .NET code files with Typewriter using the generated cleanMetadata.xml.

.\typewriter.exe -v Info -m D:\cleanMetadata.xml -o outputDirectory -g Files

  1. Clone the Beta .NET SDK https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet.
  2. Replace the files under src/Microsoft.Graph/Requests/Generated and src/Microsoft.Graph/Models/Generated in the Beta .Net SDK with the generated files.
  3. Build the Beta .Net SDK to validate that the generated files compile.

At this point you should have a valid SDK.

Using Vipr with this Writer

  1. Build the solution in Visual Studio.
  2. Go to the src\GraphODataTemplateWriter\bin\debug folder to find all compiled components.
  3. In that folder, modify .config\TemplateWriterSettings.json to specify your template mapping see Template Writer Settings for more details.
  4. Open a command prompt as administrator in the same folder and run Vipr.exe <path-or-url-to-metadata> --writer="GraphODataTemplateWriter". An example metadata file can be found in the root of this project.

By default, output source code will be put in a folder named "output" next to the Vipr executable.

Template Writer Settings

Available Languages

There is one language to choose from at the moment. TypeScript. Specify which language you want to generate in the TargetLanguage setting.

Templates

You must specify a template directory under the TemplatesDirectory Settings. The directory can be a full path or relative to the running directory. The directory must contain a sub directory for each platform you want to generate code for. See the Templates directory for an example.

Template Mapping

You must specify the mapping of T4 Templates to specific SubProcessors for each platform you wish to generate. The TemplateMapping setting is a dictionary of languages and list of templates. Each template must specify :

and optionally :

Note: Many of these optional parameters were used before Vipr had full support for annotations; now that annotations have been added to Vipr usage of these parameters should be limited to legacy scenarios

Example :

{ "Template": "EntityCollectionPage", "SubProcessor": "NavigationCollectionProperty", "Type": "Request", "Name": "<Class><Property>CollectionPage", "Matches" : "includeThisType", "Exclude" : "ExcludedTypeName;OtherExcludedTypeName" }

It is important to understand that subprocessors are mapped to methods that query the OdcmModel and return a set of OData objects. This mapping is maintained in TemplateProcess.InitializeSubprocessor(). The language specific mappings exist in the config directory. Each OData object returned by the subprocessor is applied to the mapped template which results in a code file output per each OData object.

In the above example, the objects in result set of the NavigationCollectionProperty subprocessor will each be applied to the EntityCollectionPage template. Each result will be a code file for each object returned by the NavigationCollectionProperty subprocessor.

SubProcessors

The SubProcessors determine what type of OData object will be passed into the template generating the code file.

Types

The type of template.

Template Name

To set the name of the template using the Name format string. You can insert <Class>, <Property>, <Method>, and <Container> the values will be replaced by the names of the corresponding object. If you insert an item that doesn't exist it will be replaced with an empty string. Note: You can also set the template name from inside the template by : host.SetTemplateName("foo");

Template Editing

The solution contains a non-building project to host the actual T4 templates and make browsing/editing them easier. New template files will be automatically discovered by this project.

Includes/Excludes

There may be specific times when you want to exclude or only process certain objects from the SubProcessor. To Do this you can either set a semicolon delimited list of objects you wanted to include : Include : foo;bar. This will only process objects whose names are foo or bar. The opposite of this is the exclude setting where the SubProcessor will include all objects except for those whose names are in the exclude list, exclude and include can not be used together.

Ignore/Matches

When you can't use the name of an object to include or exclude you can use the long description element on any object. Insert a long description with a semicolon delimited list of strings like : foo;bar;baz. If you add a "Matches" : "foo;baz" only objects who contain foo and baz in their long description will be processed. The opposite is true for Ignore.

Note: You can also check in a template by odcjObject.LongDescriptionContains("foo");

Note: Includes/Excludes and Ignore/Matches were used before Vipr had full support for annotations; now that annotations have been added to Vipr usage of these parameters should be limited to legacy scenarios

Building against Graph Metadata

There are currently several steps we take to form the metadata into one that will successfully generate SDKs in the shape we expect:

In order to build against metadata other than that stored in the metadata directory, you will need to perform the first four on this list.

Contributing

Before we can accept your pull request, you'll need to electronically complete Microsoft's Contributor License Agreement. If you've done this for other Microsoft projects, then you're already covered.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Why a CLA? (from the FSF)

License

Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT license.