Skip to content

Dataplane Codegen Quick Start

Jump to bottom
Yuchao Yan edited this page Jan 13, 2023 · 74 revisions

Getting Started - Generate SDK With Dataplane Codegen and Cadl

Note: if you’re still generating SDK from Swagger with DPG, please read Dataplane Codegen Quick Start For Swagger

Support

For more questions and general overview of the process, please refer to https://aka.ms/azsdk/dpcodegen

Prerequisites

Setup your repo

  • Fork and clone the azure-sdk-for-python repo (we call it's name SDK repo and it's absolute path {SDK_REPO_ROOT})

  • Create a branch in SDK repo to work in

  • Fork and clone the azure-rest-api-specs repo in the same folder with SDK repo(we call it Rest repo)

Project service name and package name

Two key pieces of information for your project are the service_name and package_name.

The service_name is the short name for the Azure service. The service_name should match across all the SDK language repos and should be name of the directory in the specification folder of the azure-rest-api-specs repo that contains the REST API definition file. An example is Service Bus, whose API definitions are in the specifications/servicebus folder of the azure-rest-api-specs repo, and uses the service_name "servicebus". Not every service follows this convention, but it should be the standard unless there are strong reasons to deviate.

In Python, a project's package name is the name used to publish the package in PyPI. For data plane libraries (management plane uses a different convention), the package_name could be just azure-{service_name}. An example is "azure-servicebus".

Some services may need several different packages. For these cases a third component, the module_name, is added to the package_name, as azure-{service_name}-{module_name}. The module_name usually comes from the name of the REST API file itself or one of the directories toward the end of the file path. An example is the Synapse service, with packages azure-synapse, azure-synapse-accesscontrol, azure-synapse-artifacts, etc.

Project folder structure

Before we start, we probably should get to know the project folder for SDK repo.

Normally, the folder structure would be something like:

  • sdk/{service_name}/{package_name}: the PROJECT_ROOT folder
    • azure/{service_name}/{module_name} : folder where generated code is.
    • /tests: folder of test files
    • /samples: folder of sample files
    • azure-{service_name}-{module_name}: package name. Usually, package name is same with part of ${PROJECT_ROOT} folder. After release, you can find it in pypi. For example: you can find azure-messaging-webpubsubservice in pypi.
    • there are also some other files (like setup.py, README.md, etc) which are necessary for a complete package.

More details on the structure of Azure SDK repos is available in the Azure SDK common repo.

How to generate SDK code with Dataplane Codegen

We are working on to automatically generate everything right now, but currently we still need some manual work to get a releasable package. Here're the steps of how to get the package.

  1. Configure python emitter in package.json

    In Rest repo, There shall be packages.json that is in same folder with main.cadl. Add dependency for python emitter:

    "dependencies": {
  ...
  "@azure-tools/cadl-python": "latest"
},

    nit: you need to run npm install in this folder to install the package.

  2. Configure python emitter in cadl-project.yaml

    In Rest repo, There shall be cadl-project.yaml where main.cadl of your service is. Configure python emitter with template:

     parameters:
   "python-sdk-folder":
     default: "{cwd}/azure-sdk-for-python/"
   "service-directory-name":
     default: "YOUR_SERVICE_DIRECRORY"

 options:
   "@azure-tools/cadl-python":
     "package-mode": "dataplane"
     "package-name": "YOUR_PACKAGE_NAME"
     "emitter-output-dir": "{python-sdk-folder}/sdk/{service-directory-name}/{package-name}"

    Update YOUR_PACKAGE_NAME with your package name; update YOUR_SERVICE_DIRECRORY with real directly. For example, assume that package name is "azure-ai-anomalydetector" and you want to put it in folder "azure-sdk-for-python/sdk/anomalydetector", then replace "YOUR_PACKAGE_NAME" with "azure-ai-anomalydetector" and replace "YOUR_SERVICE_DIRECRORY" with "anomalydetector"

    nit: To avoid duplicated configuration, you can commit the change to Rest repo.

  3. Run cmd to generate the SDK

    We need to configure python-sdk-folder and generated code will be in emitter-output-dir configured in cadl-project.yaml.

    Step into folder where main.cadl is and run the following cmd(please replace "YOUR_SDK_REPO_PATH" with your local sdk repo path like: "D:\azure-sdk-for-python"):

    cadl compile main.cadl --emit @azure-tools/cadl-python --arg "python-sdk-folder=YOUR_SDK_REPO_PATH"

What to do after generating the SDK code

The generated code is not enough to release at once and you need to update it for better usage experience. Please follow What to do after generating the SDK code with codegen to check the code.

Clone this wiki locally