Criar um novo Item de Tecido

Este guia abrangente mostra como criar itens personalizados no Microsoft Fabric usando o Kit de Ferramentas de Extensibilidade. Você pode escolher entre duas abordagens com base no nível de preferência e experiência.

Pré-requisitos

Antes de criar um item personalizado, verifique se você tem:

• ✅ Concluiu o Guia de Instalação e está com um ambiente de desenvolvimento funcionando.
• ✅ Sua carga de trabalho está sendo executada localmente e acessível no Fabric
• ✅ Familiaridade com TypeScript e React (para personalização)

Escolha sua abordagem

🤖 Abordagem assistida por IA (recomendada para novos desenvolvedores)

Use o GitHub Copilot para guiá-lo durante todo o processo interativamente. Perfeito para:

• Desenvolvedores novos na ferramenta Fabric Extensibility Toolkit
• Aprendendo os padrões de plataforma e as práticas recomendadas
• Obtendo explicações e orientação enquanto trabalha

🛠️ Abordagem manual com script (recomendado para desenvolvedores experientes)

Use o script automatizado do PowerShell para configuração rápida. Perfeito para:

• Desenvolvedores familiarizados com a estrutura do kit de ferramentas
• Criando vários itens com eficiência
• Fluxos de trabalho de produção e automação

🤖 Criação de Itens Assistida por IA

Introdução ao GitHub Copilot

O GitHub Copilot pode guiá-lo por meio da criação de um item do Fabric personalizado completo seguindo todas as práticas recomendadas. A IA entende os padrões do Kit de Ferramentas de Extensibilidade e ajudará você a implementá-los corretamente.

Prompts de exemplo que funcionam

Aqui estão prompts comprovados que impulsionarão a criação de itens:

Criação básica de item:

@fabric create a new item called MyDataReport that shows data analysis reports

Requisitos específicos:

@fabric create a custom item for managing data pipelines with these features:
- Pipeline configuration interface
- Status monitoring dashboard  
- Error handling and retry logic

Item complexo com integração do OneLake:

@fabric create an item called DataExplorer that:
- Browses OneLake files in the left panel
- Shows file preview in the center
- Saves user preferences and settings

Processo típico assistido por IA

A abordagem assistida por IA segue esse padrão iterativo:

1. Fase inicial de planejamento

• A IA analisa seus requisitos
• Sugere componentes e estrutura de itens
• Cria um plano de desenvolvimento com todos

2. Geração de componentes

• Cria o padrão de 4 arquivos (Definição, Editor, Vazio, Faixa de Opções)
• Implementa interfaces TypeScript adequadas
• Configura os componentes Fluent UI

3. Implementação de funcionalidades

• Adiciona sua funcionalidade específica
• Integra-se às APIs do Fabric
• Implementa o tratamento de erros adequado

4. Teste e refinamento

• Testa o item em seu ambiente de desenvolvimento
• Corrige todos os problemas encontrados
• Otimiza o desempenho e a experiência do usuário

Trabalhando com o Assistente de IA

Comece com requisitos claros:

I want to create a [ItemType] item that [primary purpose]. 
The item should have [list key features].
Users should be able to [list main actions].

Iterar e refinar:

The item looks good, but I need to add [specific feature]

How can I integrate this with OneLake storage?

Can you add error handling for when the API is unavailable?

Peça explicações:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Práticas recomendadas para colaboração de IA

• Seja específico: forneça requisitos e contexto claros
• Examinar cada etapa: entender o código gerado antes de continuar
• Fazer perguntas: solicitar explicações para padrões que você não entende
• Testar com frequência: executar e testar o item após cada alteração principal
• Acompanhamento: solicitar refinamentos e melhorias

Ferramentas e Ambiente de Desenvolvimento de IA

Esse repositório funciona excepcionalmente bem com ferramentas de programação de pares de IA. Se você desenvolver localmente ou em Codespaces do GitHub, poderá usar o GitHub Copilot ou outros assistentes de IA para acelerar tarefas como editar componentes do React, atualizar rotas ou gerar scaffolding de teste.

Áreas específicas de assistência de IA:

• Use a IA para elaborar componentes de editor/exibição de itens e, em seguida, adaptar-se aos padrões de API do host usados no Starter-Kit
• Peça à IA para resumir o manifesto da carga de trabalho e propor conjuntos de permissões mínimos
• Em codespaces, o Copilot está disponível no navegador ou na área de trabalho do VS Code; manter o servidor de desenvolvimento em execução para ver as alterações instantaneamente

Iteração e depuração rápidas

A estrutura de extensibilidade foi projetada para desenvolvimento rápido ao usar assistência de IA.

• Com o servidor de desenvolvimento e o DevGateway em execução, as alterações de código em seu aplicativo são refletidas imediatamente quando você abre seu item dentro do Fabric
• Você pode depurar usando as ferramentas de desenvolvimento do navegador enquanto a carga de trabalho está hospedada no iFrame do Fabric
• Iterar rapidamente na interface do usuário, nas rotas e na configuração de manifesto e validar o comportamento de ponta a ponta no workspace do Fabric
• As ferramentas de IA podem ajudar a identificar e corrigir problemas em tempo real à medida que você desenvolve

Linha do tempo esperada

• Item Simples: 30 a 60 minutos com orientação de IA
• Item Complexo: 1 a 3 horas com várias iterações
• Item Avançado: Meio dia com personalização extensa

🛠️ Abordagem manual com script

Usando o script CreateNewItem.ps1

A abordagem manual usa um script automatizado do PowerShell que copia o modelo de item HelloWorld e o configura para seu novo item.

Início Rápido

1. Navegue até o diretório de script:

   cd scripts\Setup
   

2. Execute o script de criação:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

O que o script faz

Criação de arquivo automatizada:

• ✅ Copia todos os 4 arquivos de componentes principais do modelo HelloWorld
• ✅ Renomeia arquivos para corresponder ao nome do item
• ✅ Atualiza todas as referências e importações internas
• ✅ Cria arquivos de manifesto (configurações XML e JSON)
• ✅ Copia e renomeia ativos de ícone

Estrutura de arquivo gerada:

Workload/app/items/MyCustomItemItem/
├── MyCustomItemDefinition.ts         # Data model and interfaces
├── MyCustomItemEditor.tsx            # Main editor component
├── MyCustomItemEditorEmpty.tsx       # First-time user experience
├── MyCustomItemEditorRibbon.tsx      # Action buttons and toolbar
└── MyCustomItem.scss                 # Styling

Workload/Manifest/items/MyCustomItem/
├── MyCustomItemItem.xml              # Item type definition
└── MyCustomItemItem.json             # Item configuration

Workload/Manifest/assets/images/
└── MyCustomItemItem-icon.png         # Item icon

Etapas manuais necessárias

Depois de executar o script, você deve concluir estas etapas de configuração manuais:

1. Atualizar arquivos 🚨 de ambiente CRÍTICOS

Adicione seu novo item à ITEM_NAMES variável em TODOS os arquivos de ambiente:

Arquivos a serem atualizados:

• Workload\.env.dev
• Workload\.env.test
• Workload\.env.prod

Alterar de:

ITEM_NAMES=HelloWorld

Altere para:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Sem esta etapa, seu item NÃO aparecerá na carga de trabalho!

2. Atualizar configuração de Product.json

Adicione a configuração do item a Workload\Manifest\Product.json:

{
  "items": [
    {
      "name": "HelloWorldItem",
      // ... existing config
    },
    {
      "name": "MyCustomItemItem",
      "displayName": "My Custom Item",
      "description": "Description of what your item does",
      "contentType": "MyCustomItem",
      "configurationSections": []
    }
  ]
}

3. Adicionar cadeias de caracteres de localização

Atualizar arquivos de tradução em Workload\Manifest\assets\locales\:

Em en-US.json (e em outros arquivos de localidade):

{
  "MyCustomItemItem": {
    "displayName": "My Custom Item",
    "description": "Description of your custom item"
  }
}

4. Adicionar Configuração de Roteamento

Atualize Workload\app\App.tsx para incluir o roteamento do novo item:

// Add import
import { MyCustomItemEditor } from "./items/MyCustomItemItem/MyCustomItemEditor";

// Add route in the Routes section
<Route path="/MyCustomItemItem-editor" element={<MyCustomItemEditor {...props} />} />

Etapas de verificação

Depois de concluir todas as etapas manuais:

1. Crie o projeto:

   npm run build
   

2. Reinicie o servidor de desenvolvimento:

   .\scripts\Run\StartDevServer.ps1
   

3. Teste no Fabric:

   • Navegue até sua carga de trabalho no Fabric
   • Verifique se o novo tipo de item aparece na caixa de diálogo de criação
   • Criar uma instância e verificar se ela é carregada corretamente

Práticas recomendadas e diretrizes

Por que não renomear HelloWorld?

O item HelloWorld serve como o modelo de referência que recebe atualizações regulares da Microsoft. Principais motivos para mantê-lo inalterado:

• Atualizações e melhorias: a Microsoft atualiza regularmente o HelloWorld com novos recursos, correções de bugs e práticas recomendadas
• Teste de integração: HelloWorld garante que seu ambiente esteja funcionando corretamente
• Documentação de referência: ele serve como documentação dinâmica para padrões de implementação
• Compatibilidade com versões anteriores: as atualizações mantêm a compatibilidade com personalizações existentes

Fluxo de trabalho recomendado

1. Manter HelloWorld Intacto: use-o como Item de referência e teste
2. Criar novos itens: use o script ou a assistência de IA para criar itens separados
3. Atualizações regulares: Realizar periodicamente pull de atualizações do repositório base
4. Padrões de mesclagem: aplicar novos padrões do HelloWorld atualizado aos seus itens personalizados

Práticas recomendadas de desenvolvimento de itens

Arquitetura de componente:

• ✅ Siga o padrão de 4 componentes (Definição, Editor, Vazio, Faixa de Opções)
• ✅ Usar o contêiner ItemEditor para layout e comportamento consistentes
• ✅ Implementar estados de carregamento adequados e tratamento de erros
• ✅ Seguir os padrões de design do Fluent UI

Gerenciamento de dados:

• ✅ Usar saveWorkloadItem() para itens com dados complexos
• ✅ Use getWorkloadItem() para carregar com padrões de fallback
• ✅ Implementar interfaces TypeScript adequadas no arquivo definition
• ✅ Lidar com estados indefinidos/vazios de forma elegante

Experiência do usuário:

• ✅ Fornecer estados vazios claros para usuários iniciantes
• ✅ Usar indicadores de carregamento adequados
• ✅ Implementar mensagens de erro úteis
• ✅ Siga os padrões de design do Fabric e as diretrizes de acessibilidade

Considerações sobre desempenho

• Carregamento lento: carregar somente dados quando necessário
• Atualizações eficientes: usar padrões react para minimizar renderizações
• Integração do OneLake: uso createItemWrapper() para escopo adequado
• Limites de erro: implementar o tratamento de erros adequado em todo o

Próximas etapas

Depois que o item for criado:

1. Personalizar o modelo de dados: atualizar o arquivo de definição com suas interfaces específicas
2. Implementar recursos principais: criar a funcionalidade principal no componente Editor
3. Design Empty State: Criar uma experiência de usuário de primeira vez cativante
4. Configurar Ações: Configure Ações de Faixa de Opções Apropriadas para Seu Fluxo de Trabalho
5. Teste minuciosamente: verificar todas as funcionalidades em seu ambiente de desenvolvimento
6. Preparar-se para produção: siga o guia de publicação quando estiver pronto

Resolução de problemas

O item não aparece na carga de trabalho:

• ✅ Verificar ITEM_NAMES em todos os arquivos .env
• ✅ Verificar configuração do Product.json
• ✅ Reiniciar o servidor de desenvolvimento

Erros de build:

• ✅ Verificar as interfaces do TypeScript no arquivo de definição
• ✅ Verifique se todas as importações estão corretas
• ✅ Verifique se o roteamento está configurado corretamente

Erros de runtime:

• ✅ Verificar se há mensagens de erro detalhadas no console do navegador
• ✅ Verificar a integração e a autenticação da API
• ✅ Testar com dados simplificados primeiro

Recursos adicionais

• Documentação do Controle de ItemEditor
• Guia de integração do OneLake
• Uso da API do Fabric
• Requisitos de publicação

Boa programação! 🚀