FetchXML Builder Sample

A sample Power Platform Tool Box tool that demonstrates how to port XrmToolBox tools to PPTB. This is a simplified version of the popular FetchXML Builder from XrmToolBox, reimplemented using modern web technologies.

Overview

This sample tool demonstrates:

- Visual Query Building: Select entities, attributes, and add filters through a graphical interface
- FetchXML Generation: Automatically generate FetchXML from visual selections
- Query Execution: Execute FetchXML queries against Dataverse and view results
- Modern Web UI: Responsive design using HTML/CSS/TypeScript
- PPTB API Integration: Full use of ToolBox and Dataverse APIs

Features

$3

- Load and select from available Dataverse entities
- Browse and select entity attributes
- Add multiple filter conditions with various operators
- Set top record count
- Clear and rebuild queries easily

$3

- Automatically generates FetchXML from visual builder
- View and edit generated FetchXML
- Copy FetchXML to clipboard

$3

- Execute FetchXML queries against connected Dataverse environment
- Display results in a formatted table
- Show record count

$3

- Clean, responsive interface
- Works on different screen sizes
- Loading indicators and status messages
- Error handling with user-friendly messages

Comparison with XrmToolBox Version

| Feature | XrmToolBox (XTB) | This PPTB Sample |
|---------|------------------|------------------|
| Technology | C# + Windows Forms | TypeScript + HTML/CSS |
| Platform | Windows only | Cross-platform (Windows, macOS, Linux) |
| Entity Selection | TreeView control | HTML Select + Metadata API |
| Attribute Selection | CheckedListBox | Custom checkbox list |
| Filters | Complex Windows Forms | Dynamic HTML form elements |
| Results Display | DataGridView | HTML table |
| FetchXML View | TextBox/RichTextBox | HTML textarea |
| Bundle Size | DLL (~500KB+) | ~50KB (compressed) |

Architecture

This tool uses the Full Rewrite approach (Strategy 2 from the porting guide):

1. Complete reimplementation in TypeScript/HTML
2. PPTB APIs instead of .NET SDK:
- window.toolboxAPI for connection, notifications, clipboard
- window.dataverseAPI for entity operations and metadata
3. Modern web patterns:
- Async/await for all API calls
- Event-driven UI updates
- Functional state management

Building the Tool

$3

- Node.js 18 or higher
- pnpm package manager

$3

``bash
cd examples/fetchxmlbuilder-sample
pnpm install
`

$3

`bash
pnpm run build
`

This will:
1. Compile TypeScript to JavaScript
2. Copy HTML and CSS to the dist/ folder

$3


For continuous compilation during development:
`bash
pnpm run watch
`

Installing in PPTB

$3

1. Build the tool (see above)
2. In PPTB, go to Tools → Install Tool
3. Select the dist folder or package the tool as a tarball
4. The tool will appear in your tools list

$3

Once ready for distribution:

`bash


Login to npm

npm login

Publish

npm publish
`

Users can then install via PPTB's tool marketplace or by package name.

Code Walkthrough

$3

The main TypeScript file that:
- Initializes the tool and checks connection
- Loads entities from Dataverse
- Manages application state (selected entity, attributes, filters)
- Generates FetchXML from user selections
- Executes queries and displays results

Key functions:
- init(): Initialize and check connection
- loadEntities(): Fetch entity list from Dataverse
- onEntitySelected(): Load attributes when entity is selected
- generateFetchXml(): Build FetchXML string from state
- executeQuery(): Run query and display results

$3

Clean semantic HTML structure with:
- Connection status section
- Two-column layout (query builder | results)
- Form controls for entity/attribute selection
- Filter management UI
- FetchXML display and results table

$3

Modern CSS with:
- CSS custom properties (variables) for theming
- Responsive grid layout
- Fluent Design-inspired styling
- Accessible form controls
- Clean, professional appearance

Key Porting Techniques

$3

XTB (.NET SDK):
`csharp
var metadata = service.Execute(new RetrieveEntityRequest {
LogicalName = "account",
EntityFilters = EntityFilters.Attributes
});
`

PPTB (Dataverse API):
`typescript
const response = await window.dataverseAPI.getEntityMetadata("account");
const metadata = response.data;
`

$3

XTB (Windows Forms):
`csharp
var comboBox = new ComboBox();
comboBox.DataSource = entities;
comboBox.DisplayMember = "DisplayName";
`

PPTB (HTML):
`html

-- Select --

`
`typescript
entitySelect.innerHTML = entities.map(e =>
${e.DisplayName}
).join('');
`

$3

All PPTB API calls are asynchronous:
`typescript
async function loadData() {
try {
const response = await window.dataverseAPI.retrieveMultiple('account');
// Handle success
} catch (error) {
// Handle error
}
}
`

$3

Simple object-based state:
`typescript
let selectedEntity: string | null = null;
let selectedAttributes: Set = new Set();
let filters: FilterCondition[] = [];
`

For complex tools, consider using a state management library like Redux or Zustand.

Limitations of This Sample

This is a simplified demonstration and does not include all FetchXML Builder features:

Not Implemented:
- Link-entity (joins)
- Aggregate functions (sum, count, avg, etc.)
- Order by
- Distinct results
- Paging
- Save/load queries
- FetchXML to OData/SQL conversion
- Advanced filter operators
- Complex filter groups (OR conditions)

Why These Are Excluded:
- This sample focuses on demonstrating the porting approach
- Adding all features would make the code too complex for a sample
- Core patterns shown here can be extended for additional features

Extending This Sample

To add more features:

1. Link-entity (Joins):
- Add relationship browser
- Build nested XML structure
- Display related entity attributes

2. Aggregates:
- Add aggregate function dropdown
- Modify FetchXML generation for

3. Query Persistence:
- Use window.toolboxAPI.utils.saveFile()` to export queries
- Store queries in tool-specific settings

4. Advanced UI Framework:
- Migrate to React/Vue for complex state
- Use component libraries (Fluent UI React, etc.)
- Add drag-and-drop query building

Learning Resources

- PPTB Porting Guide - Complete porting documentation
- PPTB Tool Development Guide - Tool creation guide
- PPTB Sample Tools Repository - More examples
- Dataverse Web API Reference - API documentation

Contributing

This is a sample/example tool. For improvements:
1. Fork the repository
2. Make your changes
3. Submit a pull request

License

GPL-3.0 - Same as Power Platform Tool Box

Questions?

- Open an issue in the PPTB GitHub repository
- Check the discussions board