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.

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

2. 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:

1. Capture the full error output including stack traces and error messages
2. Report the error to the user with enough context to understand what went wrong
3. 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.

Step 4: Validate Generated Schema Against Bicep Reference

After the generator runs successfully, validate the generated resources against the official Azure Bicep documentation.

Locate the Schema Log

The generator produces a schema.log file that contains the generated resource schemas:

sdk/provisioning/Azure.Provisioning.{Service}/src/Generated/schema.log

Each resource entry looks like:

resource NetworkSecurityPerimeter "Microsoft.Network/networkSecurityPerimeters@2025-05-01" = {
  name: 'string'
  location: 'string'
  ...
}

Construct Bicep Reference URLs

For each new resource type in the schema.log, construct the documentation URL:

https://learn.microsoft.com/en-us/azure/templates/{provider}/{resource-type}?pivots=deployment-language-bicep

URL Construction Rules:

• Convert the resource type from the schema to lowercase
• Use the provider and resource path from the @ prefix (e.g., Microsoft.Network/networkSecurityPerimeters)

Examples:

Schema Resource Type	Documentation URL
Microsoft.Network/networkSecurityPerimeters	https://learn.microsoft.com/en-us/azure/templates/microsoft.network/networksecurityperimeters?pivots=deployment-language-bicep
Microsoft.Network/networkSecurityPerimeters/profiles	https://learn.microsoft.com/en-us/azure/templates/microsoft.network/networksecurityperimeters/profiles?pivots=deployment-language-bicep
Microsoft.DBforPostgreSQL/flexibleServers	https://learn.microsoft.com/en-us/azure/templates/microsoft.dbforpostgresql/flexibleservers?pivots=deployment-language-bicep

Compare and Validate

For each new resource:

1. Fetch the Bicep reference from the constructed URL
2. Compare property names between schema.log and the Bicep reference
3. Check for:
   • Incorrect property names: Properties in schema.log that don't match the Bicep reference
   • Missing properties: Properties in the Bicep reference that are not in schema.log
   • Extra writable properties: Properties that are NOT marked readonly in schema.log but do NOT exist in the Bicep reference — these are potential issues since users could try to set properties that the service doesn't accept
   • Incorrectly readonly properties: Properties marked readonly in schema.log but listed as writable/required in the Bicep reference — especially the name property, which must be settable for provisionable resources
   • Type mismatches: Properties with different types

Note on readonly properties: Properties marked readonly in schema.log (e.g., provisioningState: readonly 'string') are output-only and don't need to match the Bicep reference for input validation. However, you must also check the reverse: if a property is writable/required in the Bicep reference but marked readonly in schema.log, this is a bug — the generated resource cannot be provisioned correctly.

Critical: Always validate the name property: The name property is the resource identity and should almost always be writable and required (except for singleton resources with fixed names). If schema.log shows name: readonly 'string' but the Bicep reference shows name as required, this indicates the generator failed to detect the name parameter (e.g., the ARM parameter name doesn't end with "Name", like addressId instead of suppressionListAddressName). Fix this by adding a CustomizeProperty in the specification file:

CustomizeProperty<{ResourceType}>("Name", p => { p.IsReadOnly = false; p.IsRequired = true; });

If Discrepancies Are Found

1. Report the discrepancies to the user with:
   • Which resource type has issues
   • Which properties are incorrect/missing
   • Links to the Bicep reference
2. Stop and let the user decide how to proceed — discrepancies may indicate:
   • Issues with the management library
   • Need for specification customizations
   • Documentation being out of sync (less common)

Do NOT attempt to automatically fix schema discrepancies without user guidance.

Step 5: 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:

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

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

2. Use CustomizeResource with GeneratePartialPropertyDefinition = true:

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

3. 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 CP0002 errors.

For provisioning packages, create ApiCompatBaseline.txt in the package's src/ directory to suppress the compatibility errors:

CP0002:M:Azure.Provisioning.{Service}.{EnumType}.{Member}.get->System.Runtime.Serialization.DataMemberAttribute

Note: This baseline file approach is specifically supported for provisioning

---

Content truncated.