Quick start: Run a workload sample (preview)
This quick start guide shows you how to create and run a Microsoft Fabric workload using a sample workload.
Prerequisites
Before you begin, ensure that you have the following installed on your system:
- Access to a Fabric tenant with the workload feature and developer mode enabled. See Introducing workloads for more information.
- Node.js.
- npm.
- Visual Studio 2022.
- Fabric Workload DevGateway
Step-by-step guide
Enable custom workloads
Configure the admin portal as follows:
Log into Fabric with an Admin account.
From Settings, go to the Admin portal.
In the Additional workloads (preview) section, enable the Capacity admins and contributors can add and remove additional workloads tenant setting. You can enable it for the entire organization or specific groups.
Set up the sample project
Clone the repository: Clone the repository found here: https://go.microsoft.com/fwlink/?linkid=2272254
Install dependencies: Navigate to the
Frontend
directory in the cloned repository and execute the following command:npm install
Start the local server: Launch a local Node.js server using
webpack
by running:npm start
The server typically runs on port
60006
. Confirm that the server is operational by accessing127.0.0.1:60006/manifests
and checking the .env.dev configuration file in the front-end folder.Enable frontend developer mode: In the tenant settings in the admin portal, under the Additional workloads (preview) section, and activate the Capacity admins can develop additional workloads. tenant setting. This setting allows connections to your local server and persists across browser sessions.
Run a sample workload
Once the local server is running and Developer Mode is enabled, the new sample workload appears in the menu.
- Access the sample workload: To start the Create experience, navigate to the sample workload home page.
Prepare the development environment
Clone the boilerplate: Clone the boilerplate project found here: https://go.microsoft.com/fwlink/?linkid=2272254
Open the solution: Open the solution in Visual Studio 2022 to ensure compatibility with net7.
App registration: Follow the authentication guide to set up Microsoft Entry ID authentication for secure interactions within the architecture.
Update OneLake DFS base URL: Modify the
EnvironmentConstants.cs
file in thesrc/Constants/
folder to match your environment.Configure workload settings: Update
src/Config/workload-dev-mode.json
andsrc/appsettings.json
with your specific configuration details:- Copy workload-dev-mode.json from src/Config to
C:\
and update the following fields to match your configuration:
Note
You can copy it to any other path and set up the command line argument "-DevMode:LocalConfigFilePath" in your project to specify the path.
CapacityGuid: Your capacity ID can be found within the Fabric portal under the Capacity Settings of the admin portal.
ManifestPackageFilePath: The location of the manifest package. When you build the solution, it saves the manifest package within src\bin\Debug. More details on the manifest package can be found in the later steps.
WorkloadEndpointURL: Workload endpoint URL.
In the src/appsettings.json file, update the following fields to match your configuration:
- PublisherTenantId: The ID of the workload publisher tenant.
- ClientId: Client ID (AppID) of the workload Microsoft Entra application.
- ClientSecret: The secret for the workload Microsoft Entra application.
- Audience: The audience for incoming Microsoft Entra tokens can be found in your app registration that you created under "Expose an API" section. This is also referred to as the Application ID URI.
- Copy workload-dev-mode.json from src/Config to
Configure the WorkloadManifest.xml file: Configure the WorkloadManifest.xml file with the following Microsoft Entra application details:
- AppID
- ResourceID
- RedirectURI
Generate manifest package: Build the solution to create the manifest package file, which includes validating and packing the necessary XML and JSON files.
- Trigger Fabric_Extension_BE_Boilerplate_WorkloadManifestValidator.exe on workloadManifest.xml in Packages\manifest\files\ (you can find the code of the validation process in the \workloadManifestValidator directory). If validation fails, an error file is generated specifying the failed validation.
- If the error file exists, the build fails with "WorkloadManifest validation error". You can double click on the error in VS studio and it shows you the error file.
- After successful validation, pack the WorkloadManifest.xml and FrontendManifest.json files into ManifestPackage.1.0.0.nupkg. The resulting package can be found in src\bin\Debug.
Copy the ManifestPackage.1.0.0.nupkg file to the path defined in the workload-dev-mode.json configuration file.
Run the DevGateway: Execute 'Microsoft.Fabric.Workload.DevGateway.exe' and authenticate as a capacity admin.
Start the Project: Set the 'Boilerplate' project as the startup project in Visual Studio and run it.
Additional steps
- Update the workload configuration files as needed.
- Build the solution to ensure all dependencies are correctly linked.
- Run the frontend and devgateway to establish communication with the Fabric backend.
- Create items and run jobs to test the full capabilities of your workload.