详细的设置指南

通过遵循 入门指南访问代码（在 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 执行策略设置为“不受限制”，并取消阻止文件。
• 请遵循脚本提供的指南来完成所有设置

安装程序脚本可以多次运行。 如果值已存在，系统会询问你是否希望覆盖它们。 如果要覆盖所有内容，请使用 Force 参数。

注释

如果遇到安装错误，请参阅以下故障排除部分中的 PowerShell 设置错误 。

小窍门

如果自动化安装脚本出现问题，可以按照 手动安装指南 执行分步手动配置。

步骤 2：启动开发环境

运行开发服务器（前端 + API），并通过 DevGateway 将本地实例注册到 Fabric。

# 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：在 Fabric 中启用开发人员功能

导航到 Fabric 门户并配置所需的设置：

3.1 在管理门户中配置租户设置：

转到管理门户设置并启用以下租户设置：

• 容量管理员和参与者可以添加和删除其他工作负荷
• 工作区管理员可以开发合作伙伴工作负载
• 用户可以查看和使用Microsoft未验证的其他工作负荷

3.2 打开 Fabric 开发人员模式：

导航到 Fabric 开发人员设置并启用 Fabric 开发人员模式：

现在，你已准备好在 Fabric 中创建第一个 Hello World 项目。

步骤 4：测试 HelloWorld 项

可以从工作负载中心（寻找工作负载名称）访问工作负载，或直接导航。 然后创建 Hello World 项。

步骤：

1. Open Fabric 负载中心：查找工作负荷（例如 Org.MyWorkload）。

   • 直接导航： https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
   • 将 <WORKLOAD_NAME> 替换为您的实际工作负荷名称（例如 Org.MyWorkload）

2. 创建新项：选择 Hello World 项目类型，然后选择开发工作区。

3. 验证功能：编辑器已打开，确认项按预期工作，并就像本地工件一样显示在工作区中。

祝贺！ 你在开发环境中创建了你的第一个项目。

步骤 5：开始编码

设置完成后，即可开始创建自己的自定义项。 请按照我们的综合指南学习如何创建自定义的 Fabric 项目：

📖 创建自定义纺织品指南 - 本指南提供了两种用于创建产品的方法：

• AI辅助方法：使用 GitHub Copilot 获取交互式指导（建议新开发者使用）
• 手动编写脚本方法：使用自动化 PowerShell 脚本快速设置（建议面向经验丰富的开发人员）

快速入门选项：

• 更新现有的 HelloWorld 编辑器： Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
• 或者使用脚本搭建新项的基架： ./scripts/Setup/CreateNewItem.ps1

快乐编程！ 🚀

最佳做法

• 派生存储库：派生Starter-Kit存储库，并将您的派生作为项目的基础。
• 保持同步：保持你的代码分叉与上游同步，以获取改进。
• 维护项目结构一致性：保留 Starter-Kit 的项目结构和组织模式，以确保与将来的更新兼容并保持代码清晰。
• 常规 Starter-Kit 集成：定期将 Starter-Kit 中的代码更改集成到项目中，以受益于 bug 修复、新功能和安全更新。 设置一个过程，定期查看和合并上游更改（每月或季度）。
• 提前验证清单：提前验证工作负荷清单并遵循最低特权权限。
• 使用开发容器：使用开发容器或 Codespaces 创建一致且可弃用的环境。
• 使用提供的脚本：使用提供的脚本（Setup、StartDevServer、StartDevGateway）自动执行设置和每日工作流。

排查常见问题

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 在 Chrome 中引入了新的本地网络访问（LNA）限制，这将破坏 DevServer的本地开发。 这些限制可防止网站在没有显式用户权限的情况下访问本地网络资源。

本地开发所需的作：必须更改 Chrome 配置才能在本地继续开发工作负载：

1. 在 Chrome 中导航到chrome://flags/#local-network-access-check
2. 将标志设置为“已禁用”
3. 重启 Chrome

为什么需要这一点：新的限制会阻止在 Fabric 中运行的工作负载与本地 DevGateway 服务器之间的通信，这对于开发工作流至关重要。

其他资源：

• 本地网络访问 - Chrome 开发人员 - 有关本地网络访问更改的官方 Chrome 文档

重要

如果不禁用此标志，DevGateway 的本地开发将无法在 Chrome 中使用。 仅开发环境需要此配置更改。

后续步骤

• 了解 体系结构 以及主机、应用和 Fabric 服务如何交互
• 阅读架构和最佳做法的清单概述
• 了解 工作负荷清单 结构和配置
• 使用 DevGateway 进行开发和本地测试
• 准备好广泛共享工作负荷时发布工作负荷