Lägga till tilläggsfunktioner

Funktioner definierar vad ett CLI-tillägg för Azure Developer (azd) kan göra, från att lägga till anpassade kommandon till att ansluta till distributionslivscykeln. Den här artikeln visar hur du lägger till funktioner i exempeltillägget Contoso Resource Tagger från snabbstarten Skapa ett exempeltillägg. Du kan använda samma mönster för alla tillägg.

Varje funktion kräver två saker: en post i matrisen capabilities för tilläggsmanifestet och motsvarande implementering i tilläggskoden.

Note

azd tillägg är för närvarande i betaversion.

Tillgängliga funktioner

azd tillägg kan deklarera följande funktioner:

  • custom-commands: Lägger till nya kommandon och kommandogrupper azd under tilläggets namnområde. Exempeltillägget lägger till exempel till azd tagger show. Använd den här funktionen för att exponera uppgifter som användarna kör direkt från kommandoraden.
  • lifecycle-events: Prenumererar på händelser som azd utlöser när det körs, till exempel preprovision, postprovision eller postdeploy. Tillägget kör anpassad logik på dessa platser utan att användaren anropar det direkt. Exempeltillägget söker till exempel efter nödvändiga taggar innan preprovision några resurser skapas.
  • service-target-provider: Registrerar ett nytt distributionsmål så azd vet hur man paketera och distribuerar en tjänst till en värd som den inte stöder direkt. Ett tjänstmål motsvarar host-värdet i azure.yaml. Du kan till exempel lägga till en provider som distribuerar en tjänst till en plattform från tredje part eller en intern värdmiljö.
  • framework-service-provider: Registrerar stöd för ett språk eller ramverk så azd vet hur man återställer, skapar och paketar den projekttypen. Detta motsvarar language-värdet i azure.yaml. Du kan till exempel lägga till byggstöd för ett språk som azd inte känner igen som standard.
  • provisioning-provider: Ersätter hur azd etablerar infrastruktur under azd provision och azd up. I stället för det inbyggda Bicep- eller Terraform-flödet definierar tillägget vad som händer. Du kan till exempel integrera ett annat infrastruktur-som-kod-verktyg eller ett anpassat distributions-API.
  • validation-provider: Bidrar med kontroller till azd valideringspipelinen som körs mot ett projekt eller en miljö. Du kan till exempel kontrollera att namngivningskonventioner, obligatoriska taggar eller säkerhetsinställningar finns på plats innan en distribution fortsätter.
  • mcp-server: Exponerar tilläggets funktioner som MCP-verktyg (Model Context Protocol) som AI-agenter, till exempel GitHub Copilot, kan identifiera och anropa. Exempeltillägget kan till exempel tillhandahålla ett suggest_tags-verktyg. Mer information finns i Lägga till en MCP-server i ett tillägg.
  • metadata: Innehåller mer omfattande kommando- och konfigurationsmetadata som azd används för att beskriva tillägget, till exempel detaljerade kommandobeskrivningar och konfigurationstips som visas i hjälputdata och IntelliSense.

Den här artikeln fokuserar på de två vanligaste funktionerna: anpassade kommandon och livscykelhändelser. Mer information om funktionen finns i mcp-serverLägga till en MCP-server i ett tillägg. Fullständig information om providerfunktionerna finns i referensdokumentationen för tilläggsramverket.

Lägga till anpassade kommandon

Med custom-commands funktionen kan tillägget registrera nya kommandon under ett namnområde i azd. Exempeltillägget använder redan den här funktionen för azd tagger show kommandot.

  1. Deklarera funktionen i extension.yaml.

    capabilities:
  - custom-commands

  2. Skapa dina kommandon med hjälp av hjälpen azdext.NewExtensionRootCommand , som registrerar standardflaggor azd och miljövariabelhantering så att du inte behöver deklarera dem manuellt:

    import "github.com/azure/azure-dev/cli/azd/pkg/azdext"

func NewRootCommand() *cobra.Command {
    rootCmd, extCtx := azdext.NewExtensionRootCommand(azdext.ExtensionCommandOptions{
        Name:  "tagger",
        Use:   "tagger <command> [options]",
        Short: "Standardize and report Azure resource tags.",
    })

    rootCmd.AddCommand(newShowCommand(extCtx))
    // Add other subcommands here.
    return rootCmd
}

    Hjälpen returnerar ett *ExtensionContext som exponerar de lösta värdena för standardflaggor, till exempel Environment och OutputFormat. Skicka kontexten till dina underkommandon och läs från den i deras RunE-hanterare i stället för att deklarera om standardflaggorna.

Prenumerera på livscykelhändelser

Med lifecycle-events funktionen kan ditt tillägg köra anpassad logik under händelser i projekt- och tjänstlivscykeln, till exempel preprovision eller postdeploy. För exempeltillägget använder du en preprovision-händelse för att kontrollera att nödvändiga taggar är angivna innan azd provisionerar några resurser.

  1. Deklarera funktionen i extension.yaml.

    capabilities:
  - custom-commands
  - lifecycle-events

  2. Lägg till ett listen kommando i tillägget. azd anropar det här kommandot för att upprätta den dubbelriktade anslutning som används för händelser. Använd byggaren azdext.NewExtensionHost för att registrera dina händelsehanterare:

    func newListenCommand() *cobra.Command {
    return &cobra.Command{
        Use:    "listen",
        Short:  "Starts the extension and listens for azd events.",
        Hidden: true,
        RunE: func(cmd *cobra.Command, args []string) error {
            ctx := azdext.WithAccessToken(cmd.Context())

            azdClient, err := azdext.NewAzdClient()
            if err != nil {
                return fmt.Errorf("failed to create azd client: %w", err)
            }
            defer azdClient.Close()

            host := azdext.NewExtensionHost(azdClient).
                WithProjectEventHandler(
                    "preprovision",
                    func(ctx context.Context, args *azdext.ProjectEventArgs) error {
                        fmt.Printf("Verifying required tags for project: %s\n", args.Project.Name)
                        // Add your tag validation logic here.
                        return nil
                    },
                )

            // Run blocks until azd closes the connection.
            if err := host.Run(ctx); err != nil {
                return fmt.Errorf("failed to run extension: %w", err)
            }

            return nil
        },
    }
}

  3. Registrera kommandot på ditt rotkommando:

    rootCmd.AddCommand(newListenCommand())

När en användare kör azd provision eller azd up anropar azd ditt tillägg och anropar hanteraren preprovision innan resurser etableras.

Filtrera tjänsthändelser

Tjänsthändelsehanterare stöder valfri filtrering så att du bara hanterar specifika tjänsttyper. Du kan till exempel endast hantera prepackage händelsen för Python containerapptjänster:

host := azdext.NewExtensionHost(azdClient).
    WithServiceEventHandler(
        "prepackage",
        func(ctx context.Context, args *azdext.ServiceEventArgs) error {
            fmt.Printf("Packaging service: %s\n", args.Service.Name)
            return nil
        },
        &azdext.ServiceEventOptions{
            Host:     "containerapp",
            Language: "python",
        },
    )

Återskapa och testa

När du har lagt till en funktion återskapar du tillägget och testar det nya beteendet:

  1. Om du använder bevakaren återskapas ändringarna automatiskt. Annars skapar du manuellt:

    azd x build

  2. Testa funktionen. För livscykelhändelser kör du ett kommando som utlöser händelsen, till exempel azd provision.

Relaterat innehåll

  • Last updated on