Provisioning Library Generation

Provisioning Library Generation

This skill covers two related generation workflows for Azure.Provisioning.* libraries:

• Onboarding — introducing a brand new Azure.Provisioning.{Service} package.
• Regeneration — updating an existing package to add new resources, enum values, or API versions.

> Start here: Use Workflow Selection below to choose the correct process before doing anything else.

Workflow Selection

Is this onboarding or regeneration?

• If sdk/{service}/Azure.Provisioning.{Service}/ already exists → Regeneration. Jump to Regeneration Workflow.
• If it does NOT exist → Onboarding. Read and follow ONBOARDING.md in this skill directory. New provisioning libraries are onboarded through the TypeSpec provisioning emitter.

Regeneration Workflow

(For existing packages — adding new resources, enum values, or API versions.)

Step 1: Determine If Management Library Version Update Is Needed

Key principle: Only update the management library version if explicitly requested or if the feature doesn't exist in the current version. Prefer not updating to reduce the amount of changes.

• If the requirement explicitly says "update the version" → Update the version (proceed to Step 2A)

• If the requirement does NOT explicitly request a version update:
• Check if the feature already exists in the current management library:

     # Search for the resource/feature in the management library
     grep -r "NetworkSecurityPerimeterResource" sdk/{service}/Azure.ResourceManager.{Service}/

• If the feature exists → Skip version update, proceed to Step 2B
• If the feature doesn't exist → You'll need to update the version (proceed to Step 2A)

Step 2A: Update Management Library Version (If Needed)

Edit eng/centralpackagemanagement/Directory.Packages.props to update the management library version:

<PackageVersion Include="Azure.ResourceManager.{ServiceName}" Version="{NewVersion}" />

Step 2B: Check for Resource Whitelist (If Applicable)

Some specifications (like Network) use a whitelist to limit which resources are generated. Check the specification file:

cat sdk/provisioning/Generator/src/Specifications/{Service}Specification.cs

If you see a _generatedResources HashSet, add the new resource types to it:

private readonly HashSet<Type> _generatedResources = new()
{
    // ... existing resources ...
    typeof(NetworkSecurityPerimeterResource),
    typeof(NetworkSecurityPerimeterAccessRuleResource),
    // ... add all related resource types ...
};

Step 3: Run the Provisioning Generator

Navigate to the generator directory and run:

cd sdk/provisioning/Generator/src
dotnet run --framework net10.0 -- --filter {ServiceName}

Important: The generator reads from NuGet packages, NOT local source code. The version in eng/centralpackagemanagement/Directory.Packages.props determines which package version is used.

Verify Only Target Library Changed

After running the generator, verify that only the target provisioning library was modified:

git status --short -- sdk/provisioning/

The generator may regenerate other libraries (e.g., Azure.Provisioning) due to shared dependencies. Revert any changes to libraries other than the target:

# Example: If you're adding features to Azure.Provisioning.Network, revert changes to Azure.Provisioning
git checkout main -- sdk/provisioning/Azure.Provisioning/

Only keep changes to Azure.Provisioning.{TargetService}/.

Generator Errors

If the generator fails with errors:

• Capture the full error output including stack traces and error messages
• Report the error to the user with enough context to understand what went wrong
• Stop and let the user decide how to proceed — generator errors often require code changes to the generator itself or the specification files, which may need human judgment

Do NOT attempt to automatically fix generator errors without user guidance.

> Schema and Bicep-reference validation is handled by the dedicated provisioning PR review workflow. Do not duplicate that validation in this generation workflow.

Step 4: Handle Breaking Changes (Version Updates Only)

When updating management library versions, compare the generated code with the previous version. Common breaking changes include:

Type Removed

If a type is removed from the management library:

• Create a backward-compatible stub in sdk/provisioning/Azure.Provisioning.{Service}/src/BackwardCompatible/Models/
• Mark it with [EditorBrowsable(EditorBrowsableState.Never)] and [Obsolete]

Property Type Changed

If a property type changes:

• In the specification file, use CustomizeProperty to rename the new property:

   CustomizeProperty("ResourceName", "PropertyName", p => p.Name = "NewPropertyName");

• Use CustomizeResource with GeneratePartialPropertyDefinition = true:

   CustomizeResource("ResourceName", r => r.GeneratePartialPropertyDefinition = true);

• Create a partial class in BackwardCompatible/ that implements DefineAdditionalProperties() to add the old property name

Enum Ordinal Shift

If enum member ordering changes (affecting implicit numeric values):

• Use OrderEnum<T>() in the specification file to preserve the original ordering:

  OrderEnum<PostgreSqlFlexibleServerVersion>("Ver15", "Ver14", "Ver13", "Ver12", "Ver11", "Sixteen");

DataMember Attribute Removed

If [DataMember] attributes are removed from enums, ApiCompat will report CP0014 errors.

For provisioning packages, add the suppression to eng/apicompatbaselines/Azure.Provisioning.{Service}.xml:

<Suppression>
  <DiagnosticId>CP0014</DiagnosticId>
  <Target>F:Azure.Provisioning.{Service}.{EnumType}.{Member}:[T:System.Runtime.Serialization.DataMemberAttribute]</Target>
</Suppression>

> Note: This centralized suppression approach is specifically supported for provisioning packages and is the only option for suppressing these particular ApiCompat errors.

Step 5: Fix Spell Check Issues

If CI fails with "Unknown word" errors, add the words to sdk/provisioning/cspell.yaml:

  - filename: '**/sdk/provisioning/Azure.Provisioning.{Service}/**/*.cs'
    words:
      - newword1
      - newword2

Important: Use sdk/provisioning/cspell.yaml, NOT .vscode/cspell.json.

Step 6: Run Pre-Commit Checks

Before committing, invoke the pre-commit-checks skill with the service directory set to provisioning. This will handle code formatting, API export, and snippet updates.

Step 7: Update CHANGELOG and Commit

• Update the CHANGELOG at sdk/provisioning/Azure.Provisioning.{Service}/CHANGELOG.md:

   ## X.X.X-beta.X (Unreleased)

   ### Features Added

   - Added support for `{NewResource}` resources and related types.

• Stage all changes and commit:

   git add -A
   git commit -m "Add {Feature} to Azure.Provisioning.{Service}"

Example A: PostgreSQL Server Versions 17 and 18 (Version Update Required)

The requirement was to add PostgreSQL versions 17 and 18, which required updating the management library.

• Updated eng/centralpackagemanagement/Directory.Packages.props: Changed Azure.ResourceManager.PostgreSql from 1.3.1 to 1.4.1
• Ran generator: dotnet run --framework net10.0 -- --filter PostgreSql
• Handled breaking changes: Property renames, obsolete stubs, enum ordering, ApiCompatBaseline
• Fixed CI issues: Added spell check words to cspell.yaml
• Ran pre-commit checks: pwsh eng\scripts\CodeChecks.ps1 -ServiceDirectory provisioning

Example B: NetworkSecurityPerimeter Resources (No Version Update Needed)

The requirement was to add NetworkSecurityPerimeter support. The resources already existed in the current management library but weren't being generated due to a whitelist.

• Checked management library: Resources already existed in Azure.ResourceManager.Network
• Updated NetworkSpecification.cs: Added 7 resource types to _generatedResources:

   typeof(NetworkSecurityPerimeterResource),
   typeof(NetworkSecurityPerimeterAccessRuleResource),
   typeof(NetworkSecurityPerimeterAssociationResource),
   typeof(NetworkSecurityPerimeterLinkResource),
   typeof(NetworkSecurityPerimeterLinkReferenceResource),
   typeof(NetworkSecurityPerimeterLoggingConfigurationResource),
   typeof(NetworkSecurityPerimeterProfileResource),

• Ran generator: dotnet run --framework net10.0 -- --filter Network
• Ran pre-commit checks: No breaking changes (new resources only)
• Updated CHANGELOG: Documented new NetworkSecurityPerimeter support

Key Files

| File | Purpose |

|------|---------|

| eng/centralpackagemanagement/Directory.Packages.props | Management library version |

| sdk/provisioning/Generator/src/Specifications/{Service}Specification.cs | Generator customizations and resource whitelist |

| sdk/provisioning/Generator/src/Model/Specification.Customize.cs | Customization API (OrderEnum, CustomizeResource, etc.) |

| sdk/provisioning/Azure.Provisioning.{Service}/src/BackwardCompatible/ | Backward-compatible customizations |

| eng/apicompatbaselines/Azure.Provisioning.{Service}.xml | API compatibility suppressions (provisioning only) |

| sdk/provisioning/cspell.yaml | Spell check configuration for provisioning |

Troubleshooting

Resources not being generated

• Check if the specification uses a whitelist (_generatedResources)
• Verify the resource types are added to the whitelist
• Ensure the management library version is correct

Generator fails to find types

• Ensure the management library version in eng/centralpackagemanagement/Directory.Packages.props is correct and published
• Try running dotnet restore before the generator

API compatibility errors

• Use customization code to maintain backward compatibility (preferred approach):
• Create backward-compatible stubs in BackwardCompatible/Models/
• Use CustomizeProperty and CustomizeResource in specification files
• Add partial classes with DefineAdditionalProperties() for property renames
• Only [DataMember] attribute removal errors can be suppressed via the centralized XML suppression file

Enum values in wrong order

• Use OrderEnum<T>() in the specification file to control ordering

Build fails after regeneration

• Check for missing using statements
• Check for type name conflicts
• Review the specification customizations