Přidání možností rozšíření

Možnosti definují, co může rozšíření Azure Developer CLI (azd) dělat, od přidání vlastních příkazů až po připojení k životnímu cyklu nasazení. V tomto článku se dozvíte, jak přidat možnosti do ukázkového rozšíření Contoso Resource Tagger z rychlého startu sestavení ukázkového rozšíření. Stejné vzory můžete použít u libovolného rozšíření.

Každá funkce vyžaduje dvě věci: položku v capabilities poli manifestu rozšíření a odpovídající implementaci v kódu rozšíření.

Note

Rámec rozšíření azd je všeobecně dostupný. Jednotlivá rozšíření nebo možnosti můžou mít svůj vlastní stav Preview. Podrobnosti o obecné dostupnosti najdete v tématu Obecně dostupné: Azure Developer CLI (azd) Extension Framework.

Dostupné možnosti

azd Rozšíření můžou deklarovat následující možnosti:

• custom-commands: Přidává nové příkazy a skupiny příkazů do azd v rámci oboru názvů vašeho rozšíření. Například ukázkové rozšíření přidává azd tagger show. Pomocí této možnosti můžete zveřejnit úlohy, které uživatelé spouštějí přímo z příkazového řádku.
• lifecycle-events: Přihlásí odběr událostí, které azd vyvolává během svého běhu, například preprovision, postprovision nebo postdeploy. Vaše rozšíření v těchto bodech spouští vlastní logiku bez toho, aby ho uživatel volal přímo. Například ukázkové rozšíření ověřuje, zda jsou u preprovision přítomny požadované značky, ještě před vytvořením jakýchkoli prostředků.
• service-target-provider: Zaregistruje nový cíl nasazení, aby azd dokázal zabalit a nasadit službu na hostitele, kterého ve výchozím nastavení nepodporuje. Cíl služby odpovídá hodnotě host v azure.yaml. Můžete například přidat poskytovatele, který nasadí službu na platformu třetí strany nebo do interního hostitelského prostředí.
• framework-service-provider: Zaregistruje podporu pro jazyk nebo architekturu, takže azd ví, jak tento typ projektu obnovit, sestavit a zabalit. To odpovídá hodnotě language v azure.yaml. Můžete například přidat podporu sestavení pro jazyk, který azd ve výchozím nastavení nerozpozná.
• provisioning-provider: Nahrazuje způsob, jakým azd zřizuje infrastrukturu během azd provision a azd up. Místo integrovaného toku Bicep nebo Terraformu vaše rozšíření definuje, co se stane. Můžete například integrovat jiný nástroj pro infrastrukturu jako kód nebo vlastní rozhraní API pro nasazení.
• validation-provider: Přispívá ke kontrole ověřovacího azd kanálu, který běží v projektu nebo prostředí. Můžete například ověřit, že zásady vytváření názvů, požadované značky nebo nastavení zabezpečení jsou zavedeny před zahájením nasazení.
• mcp-server: Zpřístupňuje funkce vašeho rozšíření ve formě nástrojů protokolu MCP (Model Context Protocol), které můžou agenti AI, jako je GitHub Copilot, objevovat a vyvolávat. Například může ukázkové rozšíření zpřístupnit nástroj suggest_tags. Další informace najdete v tématu Přidání serveru MCP do rozšíření.
• metadata: Poskytuje podrobnější metadata o příkazech a konfiguraci, která azd používá k popisu vašeho rozšíření, například podrobné popisy příkazů a nápovědy ke konfiguraci zobrazované v nápovědě a v IntelliSense.

Tento článek se zaměřuje na dvě nejběžnější funkce: vlastní příkazy a události životního cyklu. Informace o mcp-server možnostech najdete v tématu Přidání serveru MCP do rozšíření. Úplné podrobnosti o možnostech poskytovatele najdete v referenčních informacích k rozhraní rozšíření.

Přidání vlastních příkazů

Možnost custom-commands umožňuje vašemu rozšíření registrovat nové příkazy v rámci oboru názvů v azd. Ukázkové rozšíření už tuto funkci pro azd tagger show příkaz používá.

1. Deklarujte schopnost v souboru extension.yaml.

   capabilities:
     - custom-commands
   

2. Příkazy sestavte pomocí pomocné rutiny azdext.NewExtensionRootCommand , která zaregistruje standardní azd příznaky a zpracování proměnných prostředí, abyste je nemuseli deklarovat ručně:

   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
   }
   

   Pomocná rutina vrátí hodnotu *ExtensionContext , která zveřejňuje vyřešené hodnoty standardních příznaků, například Environment a OutputFormat. Předejte kontext do dílčích příkazů a přečtěte si ho v jejich RunE obslužných rutinách místo opětovného deeklarování standardních příznaků.

Přihlášení k odběru událostí životního cyklu

Tato lifecycle-events funkce umožňuje rozšíření spouštět vlastní logiku během událostí životního cyklu projektu a služeb, například preprovision .postdeploy U ukázkového rozšíření použijte událost preprovision k ověření, zda jsou požadované tagy nastaveny předtím, než azd zřídí jakékoli prostředky.

1. Deklarujte schopnost v souboru extension.yaml.

   capabilities:
     - custom-commands
     - lifecycle-events
   

2. Přidejte do svého rozšíření příkaz listen. azd vyvolá tento příkaz k navázání obousměrného připojení používaného pro události. Použijte konstruktor azdext.NewExtensionHost k registraci obslužných rutin pro události:

   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. Zaregistrujte příkaz listen u svého kořenového příkazu:

   rootCmd.AddCommand(newListenCommand())
   

Když uživatel spustí azd provision nebo azd up, azd vyvolá vaše rozšíření a zavolá obslužnou rutinu preprovision před zřízením zdrojů.

Filtrování událostí služby

Obslužné rutiny událostí služby podporují volitelné filtrování, takže zpracováváte pouze konkrétní typy služeb. Například můžete událost prepackage zpracovat pouze pro služby aplikace v kontejneru v Pythonu:

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",
        },
    )

Opětovné sestavení a testování

Po přidání funkce znovu sestavte rozšíření a otestujte nové chování:

1. Pokud používáte sledovací proces, vaše změny se automaticky znovu sestaví. V opačném případě sestavte ručně:

   azd x build
   

2. Otestujte schopnost. V případě událostí životního cyklu spusťte příkaz, který událost aktivuje, například azd provision.

Související obsah

• Komunikace s Azd pomocí sady SDK
• Přidání serveru MCP do rozšíření
• Publikování rozšíření
• Referenční informace k rozhraní rozšíření