This repository implements the Vipr writer that generates PowerShell cmdlets for all CRUD operations, functions and actions for Microsoft Intune Graph Api support.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
This is the overview of how the PowerShell module is put together.
- Vipr.exe is run with the following arguments in order to generate the code which defines the behavior of the cmdlets.
- The build output of the GraphODataPowerShellWriter project (i.e. GraphODataPowerShellWriter.dll).
- A Graph schema (e.g. the result of calling https://graph.microsoft.com/v1.0/$metadata) - this file has the extension ".csdl" and is located in "~/TestGraphSchemas".
- The documentation that was generated in the output of Vipr gets extracted into an XML file. This XML file is used by PowerShell to display the output of the 'Get-Help' cmdlet.
- Some functionality makes more sense to be hand-written in PowerShell, so these cmdlets are written in their own modules. These modules are located in "~/src/PowerShellGraphSDK/PowerShellModuleAdditions/CustomModules".
- The outputs of the previous 3 steps (i.e. the generated cmdlets, the cmdlet documentation and the hand-written cmdlets) are combined using a PowerShell manifest file. This file has the extension ".psd1".
- The PowerShell manifest file created in the previous step is then used to import and use the module. For example, if the manifest file was called "Intune.psd1", you can in a PowerShell window run "Import-Module ./Intune.psd1" to import the module.
This is a detailed look at step 1 in the High-Level Architecture section.
- The schema definition (CSDL) file is fed into Vipr.
- The OData v4 reader which is built into Vipr is used to read the CSDL file. This reader converts the schema definition into an intermediate representation, called the ODCM Model.
- Our custom writer is passed to Vipr to process this ODCM model. The writer consists of 4 steps in order to convert the ODCM model to the final generated C# files:
- Traverse the ODCM Model (i.e. the schema) to discover each route.
- For each route, create an abstract representation of the cmdlets that represent each operation on the route.
- Convert each abstract cmdlet representation into an abstract C# representation.
- For each abstract C# representation, convert it to a string which will be written as the contents of a file.
- Improve naming of the generated cmdlets.
- See if we can add annotations to the Graph schema that can be used to create friendly names for routes.
- Find a way to generate and build cmdlets for the whole Graph schema in a reasonable amount of time.
- The number of routes (due to navigation properties) dramatically increases once the AAD entities are included.
- Get the generated cmdlet help documentation to include a link to the appropriate page in the official Graph documentation.
- Implement piping of cmdlet outputs directly into other cmdlets.
- Implement non-interactive auth.
- Auth with certificates.
- Auth with a PSCredential object.
- Ensure we get the correct auth token expiry time - this is handled by automatically refreshing the token when required.
- Create a separate repo for the scenario cmdlets (to be used as a submodule).
- Travis CI GitHub integration + test cases.
- Create a license file for the third party software we use and include it in the module.
- Update the *.psd1 file to include the correct links to the public GitHub, license file and icon.
- Create helper cmdlets which create objects that can be serialized to the types defined in the schema.
- Get OData Capability Restrictions added to the Graph schema so that cmdlets which perform disallowed operations won't be generated in the first place.
GitHub: https://github.com/Microsoft/Intune-PowerShell-SDK
Customers have expressed a lot of interest in using PowerShell to automate tasks which are currently executed through the Intune extension in the Azure Portal.
If we write each cmdlet by hand, we would need to manually update the module each time the Graph schema is updated.
Most of Intune's user base (IT Professionals) would prefer to work with PowerShell, whereas the Graph SDK is catered towards developers who would prefer to work with e.g. C#, Java and Python. This is why we need it urgently. The structure of PowerShell's syntax does not lend itself to the structure of the existing .Net/Java/Python SDK generator (see the explanation of why we have a Custom Vipr Writer).
- The architecture is built around a Microsoft Research project called Vipr.
- It generalizes the concept of transforming information from one syntax to another.
- It is essentially a modular text parser which is especially well suited to OData-style service definitions.
- The executable accepts a Reader assembly and Writer assembly.
- The Reader is able to parse the input text file into Vipr's intermediate (generic) representation.
- The Writer accepts this intermediate representation and returns a list of file objects, i.e. (string,path) pairs.
- Vipr then writes these files in the given folder structure to the output folder.
No existing PowerShell writers are available for Vipr. Also, the .Net/Java/Python Graph SDK's writer would not easily lend itself to PowerShell's syntax, behavior or best practices.
This would have been possible, but would require an extra transformation from Graph's OData schema to the OpenAPI format. With every transformation comes the risk of losing information which could be valuable in the generated PowerShell module.