새 패브릭 항목 만들기

이 포괄적인 가이드에서는 확장성 도구 키트를 사용하여 Microsoft Fabric에서 사용자 지정 항목을 만드는 방법을 보여 줍니다. 기본 설정 및 환경 수준에 따라 두 가지 방법 중에서 선택할 수 있습니다.

필수 조건

사용자 지정 항목을 만들기 전에 다음이 있는지 확인합니다.

✅ 설치 가이드를 완료하고 작업 개발 환경을 갖습니다.
✅ 워크로드가 로컬로 실행되고 패브릭에서 액세스할 수 있습니다.
✅ TypeScript 및 React에 대한 숙지(사용자 지정용)

접근 방식 선택

🤖 AI-Assisted 접근 방식 (신규 개발자에게 권장)

GitHub Copilot를 사용하여 전체 프로세스를 대화형으로 안내합니다. 완벽한 대상:

패브릭 확장성 도구 키트를 새로 사용하는 개발자
플랫폼 패턴 및 모범 사례 학습
작업하는 동안 설명 및 지침 가져오기

🛠️ 수동 스크립트 방식(숙련된 개발자에게 권장)

빠른 설치를 위해 자동화된 PowerShell 스크립트를 사용합니다. 완벽한 대상:

도구 키트 구조에 익숙한 개발자
효율적으로 여러 항목 만들기
프로덕션 워크플로 및 자동화

🤖 AI 지원 아이템 만들기

GitHub Copilot 시작하기

GitHub Copilot는 모든 모범 사례에 따라 완전한 사용자 지정 패브릭 항목을 만드는 방법을 안내할 수 있습니다. AI는 확장성 도구 키트 패턴을 이해하고 올바르게 구현하는 데 도움이 됩니다.

작동하는 샘플 프롬프트

다음은 항목 만들기를 시작할 수 있는 검증된 프롬프트입니다.

기본 항목 만들기:

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

특정 요구 사항:

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

OneLake Integration과 연계된 복잡한 항목:

@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

일반적인 AI보조 프로세스

AI 지원 접근 방식은 다음과 같은 반복적인 패턴을 따릅니다.

1. 초기 계획 단계

AI가 요구 사항을 분석합니다.
항목 구조 및 구성 요소 제안
todos를 사용하여 개발 계획 만들기

2. 구성 요소 생성

4개의 파일 패턴(정의 파일, 편집기 파일, 빈 파일, 리본 메뉴 파일)을 만듭니다.
적절한 TypeScript 인터페이스 구현
Fluent UI 구성 요소 설정

3. 기능 구현

사용자의 특정 기능 추가
Fabric API와 통합
적절한 오류 처리를 구현합니다.

4. 테스트 및 구체화

개발 환경에서 항목을 테스트하십시오
찾은 문제를 해결합니다.
성능 및 사용자 환경 최적화

AI 도우미 작업

명확한 요구 사항으로 시작합니다.

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].

반복 및 구체화:

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?

설명 요청:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

AI 협업에 대한 모범 사례

구체적: 명확한 요구 사항 및 컨텍스트 제공
각 단계 검토: 계속하기 전에 생성된 코드 이해
질문하기: 이해하지 못하는 패턴에 대한 설명 요청
자주 테스트: 각 주요 변경 후 항목 실행 및 테스트
후속: 개선 및 요청

AI 개발 도구 및 환경

이 리포지토리는 AI 쌍 프로그래밍 도구에서 매우 잘 작동합니다. 로컬 또는 GitHub Codespaces에서 개발하는 경우 GitHub 코필로트 또는 다른 AI 도우미를 사용하여 React 구성 요소 편집, 경로 업데이트 또는 테스트 스캐폴딩 생성과 같은 작업을 가속화할 수 있습니다.

팁 (조언)

Starter-Kit 리포지토리는 AI를 사용할 수 있으며, 사용자의 요구에 맞게 Hello World 항목을 조정하는 방법을 안내하는 GitHub Copilot 지침을 포함합니다. 다른 AI 도구(예: Anthropic Claude)는 동일한 지침을 따를 수 있지만 리포지토리의 지침 파일 또는 문서를 읽도록 구성해야 합니다.

특정 AI 지원 영역:

AI를 사용하여 항목 편집기/보기 구성 요소 초안을 작성한 다음, Starter-Kit 사용되는 호스트 API 패턴에 맞게 조정합니다.
AI에 워크로드 매니페스트를 요약하고 최소한의 권한 집합을 제안하도록 요청
Codespaces에서 Copilot는 브라우저 또는 VS Code 데스크톱에서 사용할 수 있습니다. 개발자 서버를 계속 실행하여 변경 내용을 즉시 확인합니다.

팁 (조언)

다른 사용자가 빌드하는 항목을 확인하려면 확장성 샘플을 열고 환경에 배포합니다. 거기서 시작하는 데 도움이 되는 다양한 항목 유형을 찾을 수 있습니다.

빠른 반복 및 디버깅

확장성 프레임워크는 AI 지원을 사용할 때 신속한 개발을 위해 설계되었습니다.

개발 서버 및 DevGateway가 실행되면 패브릭 내에서 항목을 열 때 앱의 코드 변경 내용이 즉시 반영됩니다.
워크로드가 패브릭 iFrame에서 호스트되는 동안 브라우저의 개발 도구를 사용하여 디버그할 수 있습니다.
UI, 경로 및 매니페스트 구성을 신속하게 반복하고 패브릭 작업 영역에서 엔드투엔드 동작의 유효성을 검사합니다.
AI 도구는 개발하는 동안 실시간으로 문제를 식별하고 해결하는 데 도움이 될 수 있습니다.

예상 타임라인

간단한 항목: AI 지침이 포함된 30-60분
복합 항목: 여러 반복이 있는 1-3시간
고급 항목: 광범위한 사용자 지정이 포함된 반나절

🛠️ 수동 스크립트 접근 방식

CreateNewItem.ps1 스크립트 사용

수동 방법은 HelloWorld 항목 템플릿을 복사하고 새 항목에 맞게 구성하는 자동화된 PowerShell 스크립트를 사용합니다.

빠른 시작

스크립트 디렉터리로 이동합니다.
```
cd scripts\Setup
```

만들기 스크립트를 실행합니다.

.\CreateNewItem.ps1 -ItemName "MyCustomItem"

스크립트가 수행하는 작업

자동화된 파일 만들기:

✅ HelloWorld 템플릿에서 4개의 핵심 구성 요소 파일을 모두 복사합니다.
✅ 항목 이름과 일치하도록 파일 이름을 바꿉니다.
✅ 모든 내부 참조 및 가져오기를 업데이트합니다.
✅ 매니페스트 파일(XML 및 JSON 구성)을 만듭니다.
✅ 아이콘 자산 복사 및 이름 바꾸기

생성된 파일 구조:

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

필수 수동 단계

스크립트를 실행한 후 다음 수동 구성 단계를 완료 해야 합니다 .

1. 중요한 환경 파일 🚨 업데이트

모든 환경 파일의 변수에 ITEM_NAMES 새 항목을 추가합니다.

업데이트할 파일:

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

변경 내용:

ITEM_NAMES=HelloWorld

다음으로 변경합니다.

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ 이 단계가 없으면 항목이 워크로드에 표시되지 않습니다.

2. Product.json 구성 업데이트

아이템 구성을 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. 지역화 문자열 추가

번역 파일을 Workload\Manifest\assets\locales\에서 업데이트하십시오.

In en-US.json (및 기타 로캘 파일):

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

4. 라우팅 구성 추가

새 항목의 라우팅을 포함하도록 Workload\app\App.tsx를 업데이트합니다.

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

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

확인 단계

모든 수동 단계를 완료한 후:

프로젝트를 빌드합니다.
```
npm run build
```
개발 서버를 다시 시작합니다.
```
.\scripts\Run\StartDevServer.ps1
```
패브릭에서 테스트:
- 패브릭에서 워크로드로 이동하세요
- 만들기 대화 상자에 새 항목 유형이 표시되는지 확인합니다.
- 인스턴스를 만들고 올바르게 로드되는지 확인합니다.

모범 사례 및 지침

HelloWorld의 이름을 바꾸는 것은 어떨까요?

HelloWorld 항목은 Microsoft에서 정기적인 업데이트를 받는 참조 템플릿 역할을 합니다. 변경되지 않은 상태로 유지하는 주요 이유:

업데이트 및 개선 사항: Microsoft는 새로운 기능, 버그 수정 및 모범 사례로 HelloWorld를 정기적으로 업데이트합니다.
통합 테스트: HelloWorld는 환경이 올바르게 작동하는지 확인합니다.
참조 설명서: 구현 패턴에 대한 라이브 설명서로 사용됩니다.
이전 버전과의 호환성: 업데이트는 기존 사용자 지정과의 호환성을 유지합니다.

권장 워크플로

HelloWorld를 그대로 유지: 참조 및 테스트 항목으로 사용
새 항목 만들기: 스크립트 또는 AI 지원을 사용하여 별도의 항목 만들기
정기 업데이트: 기본 리포지토리에서 주기적으로 업데이트 끌어오기
병합 패턴: 업데이트된 HelloWorld의 새 패턴을 사용자 지정 항목에 적용

항목 개발 모범 사례

구성 요소 아키텍처:

✅ 4개 구성 요소 패턴(정의, 편집기, 비어 있음, 리본 메뉴)을 따릅니다.
✅ 일관된 레이아웃 및 동작에 ItemEditor 컨테이너 사용
✅ 적절한 로드 상태 및 오류 처리 구현
✅ Fluent UI 디자인 패턴 따르기

데이터 관리:

✅복잡한 데이터가 있는 항목에 사용 saveWorkloadItem()
을 대체 기본값으로 로드하는 데 사용하세요
✅ 정의 파일에서 적절한 TypeScript 인터페이스 구현
✅ 정의되지 않은/빈 상태를 정상적으로 처리

사용자 환경:

✅ 처음 사용자에게 명확한 빈 상태 화면 제공
✅ 적절한 로드 표시기 사용
✅ 유용한 오류 메시지 구현
✅ 패브릭 디자인 패턴 및 접근성 지침 준수

성능 고려 사항

지연 로드: 필요한 경우에만 데이터 로드
효율적인 업데이트: React 패턴을 사용하여 다시 렌더링 최소화
OneLake 통합: createItemWrapper()를 적절한 범위 지정에 활용하세요
오류 경계: 전체에서 적절한 오류 처리 구현

다음 단계

항목이 만들어지면 다음을 수행합니다.

데이터 모델 사용자 지정: 특정 인터페이스로 정의 파일 업데이트
핵심 기능 구현: 편집기 구성 요소에서 기본 기능 빌드
빈 상태 디자인: 매력적인 처음 사용자 환경 만들기
작업 구성: 워크플로에 적절한 리본 작업 설정
철저한 테스트: 개발 환경의 모든 기능 확인
프로덕션 준비: 준비되면 게시 가이드 를 따르세요.

Troubleshooting

항목이 워크로드에 표시되지 않습니다.

✅ 모든 .env 파일에서 ITEM_NAMES을 확인하세요.
✅ Product.json 구성 확인
✅ 개발 서버 다시 시작

빌드 오류:

✅ 정의 파일에서 TypeScript 인터페이스 확인
✅ 모든 가져오기가 올바른지 확인
✅ 라우팅이 제대로 구성되었는지 확인

런타임 오류:

✅ 브라우저 콘솔에서 자세한 오류 메시지를 확인합니다.
✅ API 통합 및 인증 확인
✅ 먼저 간소화된 데이터로 테스트

추가 리소스

행복한 코딩! 🚀

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-15

다음을 통해 공유

새 패브릭 항목 만들기

필수 조건

접근 방식 선택

🤖 AI-Assisted 접근 방식 (신규 개발자에게 권장)

🛠️ 수동 스크립트 방식(숙련된 개발자에게 권장)

🤖 AI 지원 아이템 만들기

GitHub Copilot 시작하기

작동하는 샘플 프롬프트

일반적인 AI보조 프로세스

AI 도우미 작업

AI 협업에 대한 모범 사례

AI 개발 도구 및 환경

빠른 반복 및 디버깅

예상 타임라인

🛠️ 수동 스크립트 접근 방식

CreateNewItem.ps1 스크립트 사용

빠른 시작

스크립트가 수행하는 작업

필수 수동 단계

1. 중요한 환경 파일 🚨 업데이트

2. Product.json 구성 업데이트

3. 지역화 문자열 추가

4. 라우팅 구성 추가

확인 단계

모범 사례 및 지침

HelloWorld의 이름을 바꾸는 것은 어떨까요?

권장 워크플로

항목 개발 모범 사례

성능 고려 사항

다음 단계

Troubleshooting

추가 리소스

피드백

추가 리소스