README

THIS EXTENSION IS A PRODUCT OF TANUKI TEAM AND FOR INTERNAL USE OF AUSTRIAN POST AG ONLY

Generate C# from Avro Schema (VS Code Extension)

📄 Overview

This Visual Studio Code extension provides a quick way for schema authors to validate and generate C# code from Avro schema files (.avsc). By using the events-cli tool, this extension automates the process of converting Avro schema definitions into C# classes, making it easier to author and verify schemas.

✨ Features

Automatic C# Code Generation: Generates C# code from .avsc files using the events-cli tool. Real-time Feedback: Displays generated code in a new preview window within VS Code. Error Handling: Shows error messages in case of invalid Avro schema definitions or generation issues.

⚙️ Installation

Prerequisites

1. Install events-cli: Make sure the events-cli tool is installed on your system and available in your PATH.

   $ dotnet tool install events-cli -g
   $ events-cli --version
   

   Ensure events-cli is present in your PATH:

   • See more information in dotnet tool install from MS Learn

   The events-cli must be at least at version 3.0.3

🚀 Usage

1. There are 3 ways to activate the command:

   1. Call the context-menu with Right-Click on .avsc file and choose Generate C# from Avro Schema.
   2. By using Keybindings:
      • Open any Avro schema file (.avsc) in your VS Code editor.
      • Activate the command using Keybindings (Ctrl+Alt+W or Cmd+Alt+W/Cmd+Option+W on macOS).
      • In case the keybinding doesn't work properly for you - make sure you don't have any other command for that key-binding:
        • Ctrl+Shift+P or Cmd+Shift+P on macOS, Type Preferences: Open Keyboard Shortcuts and select it, in search bar enter Ctrl+Alt+W or Cmd+Alt+W/Cmd+Option+E on macOS
        • If the keybinding is already taken - you can either set up another available keybinding or also set the WHEN clause to "resourceFilename =~ /\\.avsc$/"/"resourceExtname == '.avsc'"
   3. By using Command Palette of VS Code:
      • Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on macOS).
      • Search for or start typing in Command Palette >Generate C# from Avro Schema and select the command.

2. View the Generated C# Code:

   • The extension will execute the events-cli generate-types command and display the generated C# code for a selected .avsc file in a new preview window.
   • If you have closed the window with the generated C# class and want to re-open it, just call the command again, it will reopen the generated .cs file.
   • If there are any errors during the code generation, they will be shown in a VS Code error message.

🔧 Troubleshooting

• events-cli is not installed or not available in the PATH. Please install it before proceeding. - If you see an error indicating events-cli is not found, ensure it is installed and in your system's PATH. Run events-cli --version to make sure it's installed.
• The installed version of events-cli (version) is not compatible with this extension. - This error suggests that you are using a too old or unstable new version. Please install the last stable version using dotnet tools install events-cli -g.
• No active editor or document found! - Ensure that a .avsc file is open in the editor when running the command using Keybinding or Command Palette.
• Your schema is correct. But your file path for storing .avsc is incorrect. The folders structure of your .avsc must be... - The .avsc file is correct, but namespace expects another structure of folders, where that file must be stored. Please, save the file according to that message.
• Invalid Avro Schema: / Failed to generate code. Ensure your schema is correct. - If you encounter schema errors, manually validate your .avsc file or use an online tool to ensure it conforms to the Avro schema specification.

🛠️ Contributing

As long as this extension is for internal usage of Post.AG, the link to the contribution chat can be found in internal Wiki of Tanuki Team. If you would like to contribute to this extension or report any issues, please find this Teams-Chat in Wiki and open an issue there.

📚 Additional Resources

• Apache Avro Documentation
• Visual Studio Code API Documentation

Extension Settings

No extra extension settings needed.

Known Issues

Sometimes the extension does not recognise the .avsc file even if it is open in an active Editor, in that case choose (click on) another file in your project and return again to the .avsc file, that will fix the issue. The same issue can appear when trying to execute the command using keybindings.

Release Notes

Look in the Changelog.

Enjoy!