다음을 통해 공유

자세한 설정 가이드

시작 가이드에 따라 코드(Codespaces 또는 로컬)에 액세스할 수 있으면 다음 단계를 수행합니다.

팁 (조언)

단계를 수동으로 수행하지 않으려면 GitHub Copilot에게 작업을 수행할 수 있도록 요청하세요. Starter-Kit 리포지토리는 AI를 사용할 수 있으며 Copilot는 설치 프로세스를 대화형으로 안내할 수 있습니다. "이 리포지토리를 시작하고 HelloWorld 샘플을 실행하도록 도와주세요." 프롬프트를 사용해 보세요.

1단계: 설치 스크립트 실행

설치 스크립트는 대부분의 구성(앱 등록, 기본값 등)을 자동화합니다.

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

설치 스크립트 참고 사항:

  • WorkloadName은 Organization.WorkloadName 패턴을 따라야 합니다. 개발에 Org.[YourWorkloadName]을 사용하십시오.
  • 기존 Microsoft Entra 앱을 다시 사용하는 경우 리포지토리 수동 설정 가이드에 설명된 대로 SPA 리디렉션 URI가 구성되어 있는지 확인합니다.
  • macOS/Linux에서 스크립트를 실행하는 데 사용합니다 pwsh .
  • PowerShell 파일을 시작해야 하는지 묻는 메시지가 표시되면 PowerShell 실행 정책이 Unrestricted로 설정되고 파일이 차단 해제되어 있는지 확인합니다.
  • 스크립트가 제공하는 지침에 따라 모든 설정을 가져옵니다.

설치 스크립트는 여러 번 실행할 수 있습니다. 값이 이미 있는 경우 값을 덮어써야 하는지 묻는 메시지가 표시됩니다. 모든 항목을 덮어쓰려면 Force 매개 변수를 사용합니다.

비고

설치 오류가 발생하는 경우 아래 문제 해결 섹션에서 PowerShell 설치 오류를 참조하세요.

팁 (조언)

자동화된 설치 스크립트에 문제가 있는 경우 수동 설치 가이드 에 따라 단계별 수동 구성을 수행할 수 있습니다.

2단계: 개발 환경 시작

개발 서버(프런트 엔드 + API)를 실행하고 DevGateway를 통해 패브릭에 로컬 인스턴스를 등록합니다.

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

3단계: 패브릭에서 개발자 기능 사용

패브릭 포털로 이동하여 필요한 설정을 구성합니다.

3.1 관리 포털에서 테넌트 설정을 구성합니다.

관리 포털 설정으로 이동하여 다음 테넌트 설정을 사용하도록 설정합니다.

  • 용량 관리자 및 기여자는 추가 워크로드를 추가 및 제거할 수 있습니다.
  • 작업 영역 관리자는 파트너 워크로드를 개발할 수 있습니다.
  • 사용자는 Microsoft에서 유효성을 검사하지 않은 추가 워크로드를 보고 작업할 수 있습니다.

테넌트 설정의 스크린샷.

3.2 패브릭 개발자 모드 켜기:

패브릭 개발자 설정으로 이동하고 패브릭 개발자 모드를 사용하도록 설정합니다.

패브릭 개발자 모드의 스크린샷.

이제 패브릭에서 첫 번째 Hello World 항목을 만들 준비가 되었습니다.

4단계: HelloWorld 항목 테스트

워크로드 허브에서 워크로드에 액세스하거나(워크로드 이름 찾기) 직접 탐색할 수 있습니다. 그런 다음, Hello World 항목을 만듭니다.

Steps:

  1. 패브릭 워크로드 허브 열기: 워크로드를 찾습니다(예: Org.MyWorkload).

    • 직접 탐색: https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
    • 실제 워크로드 이름(예: <WORKLOAD_NAME>)으로 바꾸기 Org.MyWorkload

  2. 새 항목 만들기: Hello World 항목 유형을 선택하고 개발 작업 영역을 선택합니다.

  3. 기능 확인: 편집기가 열립니다. 항목이 예상대로 작동하고 작업 영역에서 네이티브 아티팩트처럼 표시되는지 확인합니다.

축하합니다! 개발 환경에서 첫 번째 항목을 만들었습니다.

5단계: 코딩 시작

이제 모두 설정되었으므로 사용자 지정 항목 만들기를 시작할 수 있습니다. 포괄적인 가이드에 따라 사용자 지정 패브릭 항목을 만드는 방법을 알아봅니다.

📖 사용자 지정 패브릭 항목 만들기 가이드 - 이 가이드에서는 항목을 만드는 두 가지 방법을 제공합니다.

  • AI 보조 접근 방식: 대화형 지침을 제공하기 위해 GitHub Copilot 사용 (신입 개발자에게 권장)
  • 수동 스크립트 방식: 빠른 설치를 위해 자동화된 PowerShell 스크립트 사용(숙련된 개발자에게 권장)

빠른 시작 옵션:

  • 기존 HelloWorld 편집기를 업데이트합니다. Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
  • 또는 스크립트를 사용하여 새 항목을 스캐폴드합니다. ./scripts/Setup/CreateNewItem.ps1

행복한 코딩! 🚀

모범 사례

  • 리포지토리 포크: Starter-Kit 리포지토리를 포크하고 포크를 프로젝트의 기반으로 사용합니다.
  • 동기화 유지: 업스트림과 동기화된 포크를 유지하여 개선 사항을 선택합니다.
  • 프로젝트 구조 일관성 유지: Starter-Kit의 프로젝트 구조 및 조직 패턴을 유지하여 향후 업데이트와의 호환성을 보장하고 코드 명확성을 유지합니다.
  • 정기적인 Starter-Kit 통합: 버그 수정, 새로운 기능 및 보안 업데이트를 활용하기 위해 Starter-Kit 코드 변경 내용을 프로젝트에 정기적으로 통합합니다. 정기적으로(매월 또는 분기별) 업스트림 변경 내용을 검토하고 병합하는 프로세스를 설정합니다.
  • 초기 매니페스트 유효성 검사: 워크로드 매니페스트의 유효성을 조기에 검사하고 최소 권한 권한을 따릅니다.
  • 개발 컨테이너 사용: 일관되고 삭제 가능한 환경에 개발 컨테이너 또는 Codespace를 사용합니다.
  • 제공된 스크립트 사용: 제공된 스크립트(설치, StartDevServer, StartDevGateway)를 사용하여 설정 및 매일 워크플로를 자동화합니다.

일반적인 문제 해결

PowerShell 설정 오류

설치 스크립트를 실행하는 동안 오류가 발생하는 경우 스크립트를 실행하는 환경에서 최신 PowerShell을 설치하고 구성했는지 확인합니다.

PowerShell 설치 오류의 스크린샷.

스크립트 실행 정책 오류

다음이 발생하는 경우: cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

포트 5173이 사용 중

DevServer가 포트 5173에서 시작할 수 없는 경우 프로세스를 찾아서 종료합니다.

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

종속성 오류

누락된 종속성에 대한 오류가 발생하는 경우:

# From Workload folder
cd Workload
npm install

DevGateway 인증 문제

DevGateway를 시작할 때 인증이 실패하는 경우:

  1. Microsoft Entra에서 앱 등록 리디렉션 URI 확인
  2. 테넌트 설정에서 필요한 개발자 기능을 허용하는지 확인합니다.
  3. DevGateway에서 올바른 테넌트에 로그인했는지 확인합니다.

포괄적인 문제 해결 정보는 Starter-Kit 리포지토리 추가 정보를 참조하세요.

중요 참고 사항

새 Chrome 로컬 네트워크 액세스 제한

Google은 DevServer를 사용하여 로컬 개발을 중단하는 Chrome에 새로운 LNA(로컬 네트워크 액세스) 제한을 도입했습니다. 이러한 제한 사항으로 인해 웹 사이트는 명시적 사용자 권한 없이 로컬 네트워크 리소스에 액세스할 수 없습니다.

로컬 개발에 필요한 작업: 로컬에서 워크로드를 계속 개발하려면 Chrome 구성을 변경해야 합니다.

  1. Chrome에서 chrome://flags/#local-network-access-check로 이동하십시오.
  2. 플래그를 "사용 안 함"으로 설정
  3. Chrome 다시 시작

필요한 이유: 새 제한은 패브릭에서 실행되는 워크로드와 개발 워크플로에 필수적인 로컬 DevGateway 서버 간의 통신을 차단합니다.

추가 리소스:

중요합니다

이 플래그를 사용하지 않도록 설정하지 않으면 DevGateway를 사용한 로컬 개발이 Chrome에서 작동하지 않습니다. 이 구성 변경은 개발 환경에만 필요합니다.

다음 단계

  • Last updated on