pbip
Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations.
data-goblin · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add data-goblin/power-bi-agentic-development --skill pbip技能说明
name: pbip description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations.
PBIP Project Format
PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a .pbix binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.
General, critical guidance
- This skill covers project structure, not report editing. Use
tefor the semantic model andpbirfor every report mutation. Never hand-edit PBIR JSON. - PBIX is a black box; PBIP is transparent. PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop.
- Thick vs thin reports: A thick report bundles
.Report/+.SemanticModel/in the same project (definition.pbirusesbyPath). A thin report has.Report/only, connecting to a remote model viabyConnection. Thin reports are preferred for managed/shared BI. - A project can contain multiple items. Multiple
.Report/and.SemanticModel/folders can coexist. The.pbipfile is optional -- opendefinition.pbirdirectly. - UTF-8 without BOM. All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools.
- Git line endings: PBI Desktop writes CRLF. Configure
core.autocrlfor* text=autoin.gitattributesto normalize. - 260-char Windows path limit. Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit.
- Desktop reload is selective. Use
pbir desktop refreshfor supported report/model changes; close and reopen Desktop for theme changes. - Rename cascades are cross-cutting. Rename model objects with
te mv --save, then update each report withpbir fields replaceorreplace-tableand validate both sides. - SparklineData metadata selectors embed Entity references in compact strings that do not follow the standard
SourceRef.EntityJSON structure. Easy to miss. - DAX query files exist in TWO locations:
<Name>.SemanticModel/DAXQueries/and<Name>.Report/DAXQueries/. Always check both during renames.
Working with PBIX Files
Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.
Use Power BI Desktop File > Save As > Power BI Project (.pbip), then work on the resulting
.Report folder with pbir and on the semantic model with te. If Desktop conversion is not
available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path.
PBIX vs PBIP
| Aspect | PBIX | PBIP |
|---|---|---|
| Format | Single binary file | Folder of text files |
| Source control | Not diff-friendly | Git-ready, human-readable diffs |
| Collaboration | Single author at a time | Multiple authors, merge-friendly |
| External editing | Not supported | VS Code, Tabular Editor, scripts |
| Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd |
| Data | Contains cached data | cache.abf is gitignored; metadata only in Git |
| Convert | File > Save As > PBIP | File > Save As > PBIX |
Project Structure
The .Report/ folder is required in a PBIP. The .SemanticModel/ folder is optional — a thin report has only .Report/ and points at a remote semantic model via definition.pbir byConnection.
The .pbi/ subfolders in both items (localSettings.json, editorSettings.json, cache.abf, etc.) are all optional — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.
<ProjectName>/
+-- <Name>.pbip # Entry point (references .Report folder) — optional
+-- .gitignore # Recommended; excludes .pbi/localSettings.json and cache.abf
+-- <Name>.SemanticModel/ # OPTIONAL — absent for thin reports
| +-- .pbi/ # All contents OPTIONAL, per-user runtime state
| | +-- localSettings.json # User-specific (gitignored)
| | +-- editorSettings.json # Editor settings (committed)
| | +-- cache.abf # Data cache (gitignored)
| | +-- unappliedChanges.json # Pending Power Query changes
| | +-- daxQueries.json # DAX query view tab settings
| | +-- tmdlscripts.json # TMDL view script tab settings
| +-- definition.pbism # SM entry point (required if .SemanticModel exists)
| +-- definition/ # TMDL format (preferred) — see tmdl skill
| +-- model.bim # TMSL format (legacy alt to definition/, mutually exclusive)
| +-- diagramLayout.json # SM diagram (no external edit)
| +-- DAXQueries/ # .dax files from DAX query view
| +-- TMDLScripts/ # .tmdl files from TMDL view
| +-- Copilot/ # Copilot tooling metadata
| +-- .platform # Fabric identity (displayName, logicalId)
+-- <Name>.Report/ # REQUIRED
| +-- .pbi/ # OPTIONAL runtime state
| | +-- localSettings.json # User-specific (gitignored)
| +-- definition.pbir # Report entry point (required for PBIR format)
| +-- definition/ # PBIR format — see pbir-format skill
| | +-- report.json
| | +-- version.json
| |
阅读完整来源 ↗