Compartilhar via

Introdução ao plug-in Power Pages para GitHub Copilot CLI e Claude Code (versão prévia)

O plug-in Power Pages para GitHub Copilot CLI e Claude Code fornece um fluxo de trabalho assistido por IA para criar, implantar e gerenciar sites modernos de aplicativos de página única (SPA) no Power Pages. Em vez de estruturar manualmente projetos, escrever código de API clichê e configurar permissões, descrever o que você deseja em linguagem natural e o plug-in manipula a implementação.

O plug-in dá suporte ao ciclo de vida de desenvolvimento de site completo por meio de habilidades de conversação, desde o scaffolding de um novo site até a implantação dele, a configuração de modelos de dados do Dataverse e a configuração da autenticação.

Importante

  • Este recurso está em versão preliminar.
  • As versões prévias do recurso não foram criadas para uso em ambientes de produção e podem ter funcionalidade restrita. Esses recursos estão disponíveis antes de um lançamento oficial para que os clientes possam obter acesso antecipadamente e fornecer feedback.
  • Examinar as propostas do agente antes de aprovar

Pré-requisitos

Antes de começar, verifique se você tem o software e as permissões necessários.

Requisitos de software

Componente Versão mínima Mais informações
Node.js 18.0 ou posterior Baixar Node.js
CLI do Power Platform (CLI do PAC) 2.6.3 ou posterior (necessário para a lógica do servidor) Instalar a CLI do PAC
CLI do Azure Mais recente Instalar CLI do Azure
GitHub Copilot CLI ou Código Claude Mais recente GitHub Copilot CLI ou Claude Code
Extensão do Visual Studio Code e do Power Platform Tools (opcional) Mais recente Baixar o VS Code e instalar ferramentas do Power Platform

Também precisa de:

  • Um ambiente do Power Platform com Power Pages habilitado.
  • Uma sessão autenticada da CLI do PAC conectada ao seu ambiente de destino. Execute o pac auth create se você ainda não se conectou.
  • Uma sessão do CLI do Azure conectada ao mesmo inquilino. Execute az login para autenticar.

Verifique a autenticação:

Verifique se você está autenticado usando o pac auth list comando.

pac auth list           # Should show authenticated profile

Se você não estiver autenticado, execute este comando:

pac auth create --environment <Instance url>        # Authenticate to Power Platform

Dica

Para obter a URL da instância, vá para Power Pages página inicial, selecione o ícone Settings no canto superior direito e selecione Session details.

Instalar o plug-in

Instale o plug-in Power Pages do marketplace. Se você usar GitHub Copilot CLI, consulte a documentação de extensões da CLI Copilot para obter etapas de instalação equivalentes. Os comandos a seguir usam a sintaxe claude code.

Execute o instalador para configurar todos os plug-ins com a atualização automática habilitada:

Windows (PowerShell):

iwr https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js -OutFile install.js; node install.js; del install.js

macOS/Linux/Windows (cmd):

curl -fsSL https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js | node

O instalador automaticamente:

  • Instala a pac CLI se ela ainda não estiver instalada.
  • Detecta ferramentas disponíveis, como Claude Code e GitHub Copilot CLI.
  • Registra o marketplace de plug-ins e instala todos os plug-ins listados.
  • Habilita a atualização automática para que os plug-ins permaneçam atualizados.

Após a instalação, reinicie o Claude Code ou GitHub Copilot CLI para acessar as habilidades do plug-in como comandos de barra na sessão do agente.

Instalar por meio do marketplace

  1. Abra o Claude Code em seu terminal.

  2. Adicione o marketplace de Microsoft:

    /plugin marketplace add microsoft/power-platform-skills

  3. Instale o plug-in Power Pages:

    /plugin install power-pages@power-platform-skills

Depois de instalar o plug-in, reinicie o Claude Code ou GitHub Copilot CLI para acessar as habilidades do plug-in como comandos de barra na sessão do agente.

Dica

Para receber atualizações e habilidades automaticamente no marketplace, ative a atualização automática. Use o /plugin comando, vá para Marketplaces, escolha o marketplace e ative a atualização automática.

Visão geral de habilidades

O plug-in fornece habilidades que abrangem todo o ciclo de vida de um site Power Pages. Chame cada habilidade de forma conversacional, seja por comando de barra ou descreva o que você deseja fazer.

Habilidade Comando O que faz
Criar site /create-site Estrutura um site, aplica sua direção de design e cria páginas e componentes
Implantar site /deploy-site Cria o projeto e o carrega para Power Pages usando a CLI do PAC
Ativar site /activate-site Provisiona um registro de site e atribui uma URL pública
Configurar o modelo de dados /setup-datamodel Cria tabelas, colunas e relações do Dataverse
Adicionar dados de exemplo (opcional) /add-sample-data Popula tabelas do Dataverse com registros de teste realistas
Integrar API da Web /integrate-webapi Gera o código do cliente de API tipada, serviços e permissões de tabela
Configurar a autenticação /setup-auth Adiciona funcionalidade de login e logout e controle de acesso baseado em funções
Criar funções da Web /create-webroles Gera arquivos YAML de função Web para gerenciamento de acesso de usuário
Adicionar lógica de servidor /add-server-logic Gera pontos de extremidade JavaScript seguros do lado do servidor para validação, chamadas de API externas, gerenciamento de segredos e operações de dados.
Adicionar fluxo de nuvem /add-cloud-flow Integra fluxos de nuvem Power Automate existentes em seu site para fluxos de trabalho de aprovação, notificações e automação agendada
Integrar back-end /integrate-backend Analisa seu protótipo, determina a abordagem certa (API Web, Lógica do Servidor ou fluxo de nuvem) para cada recurso e orquestra a sequência de build completa
Adicionar SEO /add-seo Gera robots.txt, sitemap.xml e meta tags

Fluxo de trabalho típico

Um fluxo de trabalho de ponta a ponta comum segue esta sequência:

  1. /create-site : estruturar, desenhar e construir páginas
  2. /deploy-site: faça upload para o seu ambiente do Power Pages
  3. /activate-site : configurar uma URL pública
  4. /setup-datamodel : Criar tabelas do Dataverse
  5. /add-sample-data : preencher tabelas com registros de teste
  6. /integration-webapi : gerar código do cliente de API e configurar permissões
  7. /create-webroles: Definir funções de acesso
  8. /setup-auth : adicionar entrada, saída e interface do usuário baseada em função
  9. /add-server-logic : Adicionar endpoints seguros do lado do servidor
  10. /add-cloud-flow: integrar fluxos de Power Automate existentes
  11. /add-seo : otimização do mecanismo de pesquisa
  12. /deploy-site : enviar por push as alterações finais ao vivo

Dica

  • Você não precisa seguir esta ordem exata. Cada habilidade verifica seus próprios pré-requisitos e informa se algo está ausente. Por exemplo, você pode executar /setup-auth antes /integrate-webapi se seu site precisar de autenticação primeiro.
  • Se você não tiver certeza de qual abordagem usar para cada recurso, execute /integrate-backend em vez das etapas 4 a 10 individualmente. Ele analisa seu protótipo, determina se cada recurso precisa de API Web, Lógica do Servidor ou um fluxo de nuvem e orquestra as habilidades na ordem correta.

Criar seu site de Power Pages

Este passo a passo aborda todo o ciclo de vida da criação de um site de Power Pages com o plugin, desde a estruturação até a implantação. Cada etapa descreve o que você diz e o que o plug-in faz em resposta.

Etapa 1: Criar seu site

Descreva o site que você deseja em linguagem natural: para o que ele é, para quais páginas ele precisa e quaisquer preferências de design, como esquema de cores, estilo de layout ou fontes. Execute /create-site ou apenas descreva seu site e o plug-in reconhece a intenção.

Se você não especificar uma estrutura, o plug-in solicitará que você escolha uma (React, Vue, Angular ou Astro), em seguida:

  1. Estrutura o projeto a partir de um template e aplica o nome do seu site, as cores e os tokens de design.
  2. Instala dependências, inicia um servidor de desenvolvimento e abre uma visualização do navegador ao vivo.
  3. Cria cada página, componente e rota solicitadas com imagens relevantes.
  4. Cria confirmações do git em marcos significativos para que você tenha um histórico de reversão integrado.

Etapa 2: Implantar seu site

Execute /deploy-site para carregar seu site para Power Pages. O plug-in:

  1. Verifica se a CLI do PAC está instalada e sua sessão de autenticação está ativa.
  2. Confirma o ambiente de destino com você antes de continuar.
  3. Executa um build de produção e carrega a saída compilada.
  4. Cria um diretório de artefatos de implantação caso ainda não exista.

Observação

Se o ambiente bloquear determinados anexos de arquivo, o plug-in detectará o problema e fornecerá instruções para resolvê-lo.

Etapa 3: Ativar seu site

Execute /activate-site para tornar o site publicamente acessível. O plug-in:

  1. Sugere um subdomínio com base no nome do site e permite personalizá-lo.
  2. Provisiona um registro de site por meio da API do Power Platform.
  3. Aguarde até que o site esteja ativo e retorne a URL pública.

Neste ponto, você tem um site de trabalho em uma URL pública. As etapas restantes adicionam dados, autenticação e SEO. Ignore as etapas que não se aplicam ao seu site.

Etapa 4: Configurar seu modelo de dados

Execute /setup-datamodel para criar as tabelas do Dataverse de que seu site precisa. Se você já tiver um diagrama de ER ou um esquema específico, forneça-o diretamente em vez de fazer com que o agente analise seu código.

O plug-in gera um agente do Arquiteto de Modelos de Dados que:

  1. Analisa o código do site para determinar quais dados as páginas e os componentes exigem.
  2. Consulta o ambiente do Dataverse em busca de tabelas existentes para evitar duplicatas.
  3. Propõe um modelo de dados com tabelas, colunas, tipos de dados e relações, visualizados como um diagrama de ER.

Examine e aprove a proposta. O plug-in não cria nada até que você confirme. Após a aprovação, o plug-in cria as tabelas e colunas por meio de chamadas à API e salva um arquivo de manifesto que as Etapas 5 e 6 usam.

Etapa 5: Adicionar dados de exemplo (opcional)

Execute /add-sample-data para preencher suas tabelas com registros de teste. Esta etapa requer o modelo de dados da Etapa 4.

O plug-in executa as seguintes ações:

  1. Lê o manifesto para entender suas tabelas, colunas e relações.
  2. Gera valores contextualmente apropriados para cada tipo de coluna, como emails realistas, datas plausíveis e valores de moeda formatados.
  3. Insere registros na ordem de dependência (tabelas pai antes das tabelas filho) e atualiza os tokens de autenticação automaticamente durante inserções em massa.

Etapa 6: Integrar com a API Web do Dataverse

Execute /integrate-webapi para substituir dados fictícios por consultas dinâmicas do Dataverse. Esta etapa requer o modelo de dados da Etapa 4.

O plug-in executa as seguintes ações:

  1. Verifica sua base de código em busca de componentes que usam dados fictícios, chamadas de busca de espaço reservado ou matrizes codificadas. Ele mapeia esses componentes para suas tabelas do Dataverse.
  2. Gera um agente de Integração de API Web para cada tabela que gera:
    • Um cliente de API compartilhado com gerenciamento de token antifalsificação e lógica de tentativas.
    • Tipos de entidade TypeScript e mapeadores de domínio.
    • Uma camada de serviço CRUD.
    • Padrões específicos de frameworks, como hooks do React, composables do Vue.js ou serviços do Angular.
  3. Gera um agente do Arquiteto de Permissões que propõe permissões de tabela e configurações de site.

Examine e aprove a proposta de permissões. O plug-in não cria nenhum arquivo de configuração até que você confirme.

Etapa 7: Criar funções da Web

Execute /create-webroles para definir funções de acesso do usuário. O plug-in:

  1. Consulta seu ambiente em busca de funções Web existentes para evitar duplicatas.
  2. Gera definições de função com identificadores exclusivos.
  3. Impõe que cada site tenha no máximo uma função anônima e uma função autenticada.

Etapa 8: Configurar a autenticação

Execute /setup-auth para adicionar a funcionalidade de entrada e de saída. O plug-in:

  1. Gera um serviço de autenticação para o fluxo de Microsoft Entra ID com gerenciamento de token anti-falsificação.
  2. Cria um componente de UI de login/logout integrado ao layout do site.
  3. Adiciona utilitários de controle de acesso baseados em função que mostram ou ocultam elementos da interface com base nos papéis web do usuário.
  4. Usa os padrões de sua estrutura por toda parte (React hooks, composáveis do Vue ou serviços do Angular).

Etapa 9: Adicionar lógica do servidor

Use /add-server-logic para adicionar endpoints seguros do lado do servidor ao seu site. Use a Lógica do Servidor quando seu site precisar de lógica que não possa ser executada no navegador, como chamadas à API externas, validação do lado do servidor, gerenciamento de segredo ou operações de dados entre entidades.

Importante

O suporte à lógica do servidor requer a versão 2.6.3 ou posterior do PAC CLI. Use o script de instalação rápida para atualizar para a versão mais recente.

Descreva o que você precisa em linguagem simples e o plug-in:

  1. Gera um agente do Arquiteto Lógico do Servidor que analisa seu caso de uso e classifica sua complexidade.
  2. Propõe um design de endpoint, uma configuração de segurança e todas as permissões de tabela necessárias para sua revisão.
  3. Depois de aprovar, gera o ponto de extremidade JavaScript do lado do servidor em /_api/serverlogics/<name>.
  4. Cria um serviço de cliente tipado para acionar o endpoint dos seus componentes.
  5. Atualiza seus componentes para chamar o novo serviço.
  6. Configura atribuições de função web e permissões de tabela para o ponto de extremidade.

Examine e aprove a proposta. Nenhum código é gerado até que você confirme.

Casos de uso comuns:

Observação

Execute /add-server-logic uma vez por caso de uso. Por exemplo, se o site precisar de um ponto de extremidade de validação de inventário e de um ponto de extremidade de pesquisa global, execute a habilidade duas vezes.

Etapa 10: Integrar fluxos de nuvem

Execute /add-cloud-flow para integrar fluxos de nuvem Power Automate existentes ao seu site. Essa habilidade conecta seu site Power Pages a fluxos que você já criou no Power Automate. Ele não cria novos fluxos de nuvem.

O plug-in:

  1. Registra o fluxo de trabalho em nuvem existente no seu site.
  2. Gera código do lado do cliente para inicializar o fluxo a partir das suas páginas.
  3. Manipula o estado do fluxo de trabalho assíncrono e os padrões de retorno de chamada.
  4. Configura a troca de dados entre a página e o fluxo.

Use /add-cloud-flow para fluxos de trabalho de aprovação, notificações por email, trabalhos agendados e automação por eventos, que são mais bem tratados pelo Power Automate do que pelos endpoints do lado do servidor.

Alternativa: usar /integrar-backend para planejar a camada completa de serviço

Se você não tiver certeza de quais recursos precisam de API Web, Lógica do Servidor ou um fluxo de nuvem, execute /integrate-backend em vez de executar manualmente as etapas 4 a 10. Essa habilidade atua como um orquestrador que:

  1. Analisa seu protótipo para identificar todos os recursos que precisam de uma camada de serviço.
  2. Classifica cada recurso na abordagem certa: API Web para CRUD padrão, Lógica do Servidor para validação do servidor e APIs externas ou fluxo de nuvem para fluxos de trabalho de aprovação e automação.
  3. Propõe um plano de execução sequenciado com todas as habilidades, dependências e configurações.
  4. Depois de você aprovar, o sistema orquestra as habilidades na ordem correta.

O plano é persistente, retomável e editável. Pare após qualquer etapa para examinar o código gerado ou testar o site e retome de onde parou executando /integrate-backend novamente.

Etapa 11: Adicionar SEO

Execute /add-seo para otimizar seu site para mecanismos de pesquisa. O plug-in:

  1. Descobre rotas da configuração do roteador da estrutura.
  2. Gera diretivas do mecanismo de pesquisa e um mapa de site para todas as rotas descobertas.
  3. Adiciona marcas meta: visor, conjunto de caracteres, descrição, Open Graph, Twitter Card e referências de favicon.

Etapa 12: Implantar o site final

Se você executar quaisquer etapas opcionais, execute /deploy-site novamente para efetuar push das alterações ao vivo. O plug-in executa um build de produção e carrega o site junto com todos os artefatos de implantação (permissões de tabela, configurações de site, funções web, arquivos lógicos do servidor) para o ambiente Power Pages.

Verificar seu site

Depois de concluir as habilidades, verifique se o Power Pages site funciona corretamente.

  1. Vá para Power Pages.
  2. Localize seu site na lista de sites ativos .
  3. Visualizar seu site na área de trabalho usando a opção Visualizar .
  4. Teste a funcionalidade.

Dicas e práticas recomendadas

As dicas a seguir ajudam você a aproveitar ao máximo o plug-in e o agente de codificação de IA ao criar Power Pages sites.

Verifique a saída do terminal para ferramentas ausentes na primeira vez que é executado

O plug-in fornece as habilidades e fluxos de trabalho, mas o agente de codificação de IA - GitHub Copilot CLI ou Claude Code - executa os comandos reais em seu computador. Ao usar essas ferramentas pela primeira vez, observe a saída do terminal de perto. O agente de codificação de IA executa comandos e scripts nos bastidores, e alguns desses comandos dependem de ferramentas que podem não ser instaladas em seu computador. Se uma etapa falhar, a saída do terminal geralmente mostrará qual ferramenta ou comando não foi possível encontrar.

Se você vir um erro como command not found ou is not recognized, instale a ferramenta ausente e dispare novamente o fluxo de trabalho. O agente de codificação de IA continua de onde parou assim que a ferramenta esteja disponível.

Examinar as propostas do agente antes de aprovar

Os agentes arquiteto de modelo de dados e arquiteto de permissões de API Web apresentam propostas antes de fazer alterações. Reserve um tempo para examinar essas propostas com cuidado.

  • Propostas de modelo de dados: verifique se os nomes de tabela, os tipos de coluna e as relações correspondem aos seus requisitos de negócios. É muito mais fácil ajustar uma proposta do que renomear colunas depois que os dados já estiverem inseridos.
  • Propostas de permissões: verifique se cada função tem o nível de acesso correto (criar, ler, atualizar, excluir) para cada tabela. Permissões de tabela excessivamente permissivas são um risco de segurança comum.

Cole erros diretamente no contexto

Quando algo falhar, seja um erro de build, uma falha de implantação ou uma exceção de runtime no navegador, copie a saída de erro completa. Cole-o junto com uma breve descrição do que você estava fazendo. Quanto mais contexto você fornecer, mais rápido será a correção.

Exemplo: erro de build

I ran npm run build and got this error. Fix it.

error TS2339: Property 'jobTitle' does not exist on type 'JobPosting'.

  src/components/JobCard.tsx:24:31
    24   <Text>{posting.jobTitle}</Text>

Dica

Inclua o nome do arquivo, o comando que você executou e o que você esperava que acontecesse. O plug-in usa esse contexto para localizar o problema e aplicar uma correção direcionada em vez de adivinhar.

Compartilhar erros de API Web com a URL de solicitação completa

Um problema comum após a implantação é um erro 403 da API Web Power Pages quando uma coluna não está habilitada para acesso à API. Quando encontrar esse erro, cole a URL de API completa e a resposta completa de erro JSON. A mensagem de erro informa exatamente qual tabela e coluna precisam ser corrigidas, e o plug-in pode atualizar a permissão de tabela YAML e as configurações do site para você.

Exemplo: Coluna não habilitada para API Web (403)

I'm getting a 403 error when the documents page loads. Here's the API call and the response. Fix the issue so this API works.

URL:
https://my-site.powerappsportals.com/_api/crd50_documents?$select=crd50_documentid,crd50_name,crd50_documentcategory,crd50_filetype,crd50_filesize,crd50_updateddate,crd50_description,_crd50_propertyid_value

Response:
{
  "error": {
    "code": "90040101",
    "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
    "innererror": {
      "code": "90040101",
      "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
      "type": "AttributePermissionIsMissing"
    }
  }
}

Esse erro (AttributePermissionIsMissing) significa que a coluna _crd50_propertyid_value de pesquisa existe na tabela Dataverse, mas não está listada na configuração de permissão de tabela para a API Web. O plug-in resolve esse erro adicionando a coluna ausente ao arquivo YAML de permissão da tabela em .powerpages-site/table-permissions/ e reimplantando.

Observação

Power Pages API Web requer que todas as colunas retornadas por uma chamada à API sejam explicitamente listadas na permissão de tabela. As propriedades de pesquisa (prefixadas com _ e sufixadas com _value) são fáceis de ignorar porque o nome da API difere do nome lógico da coluna no Dataverse. Quando você vir AttributePermissionIsMissing, adicione sempre aquela coluna às permissões de tabela. Não altere a consulta de API.

Seja específico sobre o que você deseja

Solicitações vagas produzem resultados vagos. Informe ao plug-in exatamente o que você precisa, incluindo preferências de layout, campos de dados e comportamento.

Em vez de Experimentar
Criar uma página para empregos "Criar uma página de listagens de vagas com uma barra de pesquisa na parte superior, chips de filtro para local e departamento, e uma grade de cartões mostrando título, empresa, faixa salarial e data de publicação para cada vaga"
"Corrigir o estilo" "Os cartões de trabalho são empilhados verticalmente na área de trabalho. Faça com que eles sejam exibidos em uma grade de três colunas com margem de 16px em telas superiores a 768px
"Adicionar alguns dados" "Adicione 20 postagens de exemplo de trabalho em quatro departamentos (Engenharia, Marketing, Vendas, RH) com títulos realistas, faixas salariais entre US$ 60 mil e US$ 180 mil e datas postadas nos últimos 30 dias"
"Configurar a API" "Conecte o componente JobListings à tabela cr_jobposting Dataverse. Substitua a matriz codificada por uma chamada de API real que busca título, departamento, salário e data postada"

Usar capturas de tela para problemas visuais

Quando o site não estiver bem no navegador, tire uma captura de tela e cole-a diretamente na conversa ou forneça um caminho de arquivo. O contexto visual ajuda a identificar problemas de layout, espaçamento e estilo difíceis de descrever no texto.

The header overlaps the hero section on mobile. Here's a screenshot:

[paste screenshot or provide path to screenshot file]

Fix the header so it doesn't overlap. It should be a fixed header with the content starting below it.

Iterar em etapas pequenas

Em vez de descrever um site inteiro em um prompt, compile incrementalmente. Comece com a estrutura e o layout e adicione recursos um de cada vez. Essa abordagem oferece a chance de revisar e corrigir o curso em cada etapa.

Step 1: /create-site → Get the basic scaffold and layout right
Step 2: "Add a hero section to the home page with a search bar"
Step 3: "Add a job listings page with filter and sort"
Step 4: "Add a job detail page that shows full description"
Step 5: /setup-datamodel → Create tables now that you know the data shape
Step 6: /integrate-webapi → Wire up real data

Dica

Após cada etapa, verifique a pré-visualização do navegador. Se algo não estiver certo, corrija-o antes de seguir em frente. É mais fácil corrigir problemas em um componente do que desembaraçar problemas em um site inteiro.

Pedir uma explicação antes de aprovar

Quando você não tiver certeza sobre uma alteração proposta, especialmente para permissões, modificações de modelo de dados ou configuração de autenticação, peça ao plugin que explique o que ele pretende fazer e por que antes de aprovar.

Before you create the table permissions, explain what access each role will have and why. I want to understand the security implications.

Executar habilidades de forma independente para se recuperar de problemas

Se uma habilidade falhar no meio do caminho, você não precisa recomeçar. Cada habilidade é executada de forma independente e pode continuar de onde parou. Por exemplo, se /integrate-webapi falhar na terceira tabela, você poderá executar novamente e ela detectará o trabalho já concluído.

/integrate-webapi failed while processing the cr_applications table. Here's the error: [paste error]. Resume the integration from where it stopped.

Conteúdo relacionado

  • Last updated on