Freigeben über

Implementieren des Microsoft Fabric-Back-Ends

  • Artikel

Dieses Microsoft Fabric-Beispielrepository für die Workloadentwicklung dient als Ausgangspunkt für die Erstellung von Anwendungen, die eine Integration mit verschiedenen Diensten erfordern, und für die Integration mit Lakehouse-Architektur. Dieser Artikel hilft Ihnen, die Umgebung einzurichten und die notwendigen Komponenten zu konfigurieren, um loszulegen. In diesem Artikel werden die wichtigsten Komponenten und ihre Rolle in der Architektur beschrieben.

Front-End

Das Front-End ist der Ort, an dem Sie die Benutzeroberfläche (User Experience, UX) und das Benutzerverhalten verwalten. Es kommuniziert mit dem Fabric Front-End-Portal über einen iFrame und erleichtert die nahtlose Interaktion.

Weitere Informationen finden Sie im Artikel zum Microsoft Fabric Workload Development Kit-Front-End.

Back-End

Das Back-End speichert sowohl Daten als auch Metadaten. Es verwendet CRUD-Vorgänge (Create, Read, Update, and Delete; Erstellen, Lesen, Aktualisieren und Löschen) zum Erstellen von Workloadelementen zusammen mit Metadaten und führt Aufträge aus, um Daten im Speicher aufzufüllen. Die Kommunikation zwischen Front-End und Back-End wird über öffentliche APIs hergestellt.

Azure Relay und DevGateway

Azure Relay ermöglicht die Kommunikation zwischen der lokalen Entwicklungsumgebung und dem Fabric-Back-End während der Arbeit im Entwicklermodus. Im Entwicklermodus wird die Workload auf dem Computer des Entwicklers ausgeführt.

Das DevGateway-Hilfsprogramm hat zwei Aufgaben:

  • Es behandelt die Seite des Azure Relay-Kanals und verwaltet die Registrierung der lokalen Workloadinstanz mit Fabric im Kontext einer bestimmten Kapazität. DevGateway macht die Workload in allen Arbeitsbereichen zugänglich, die dieser Kapazität zugewiesen sind. Das Hilfsprogramm behandelt die Registrierungsaufhebung, wenn der Kanal beendet wird.
  • Es kanalisiert zusammen mit Azure Relay Workload-API-Aufrufe von Fabric an die Workload.

API-Aufrufe für die Workloadsteuerung werden direkt von der Workload an Fabric getätigt. Der Azure Relay-Kanal ist für die Anrufe nicht erforderlich.

Lakehouse-Integration

Die Architektur des Workload Development Kits lässt sich nahtlos in eine Lakehouse-Architektur integrieren und ermöglicht Vorgänge wie das Speichern, Lesen und Abrufen von Daten. Die Interaktion wird durch Azure Relay und das Fabric SDK erleichtert, was eine sichere und authentifizierte Kommunikation gewährleistet. Weitere Informationen finden Sie unter Arbeiten mit Kundendaten.

Authentifizierung und Sicherheit

Microsoft Entra ID wird für die sichere Authentifizierung verwendet und stellt sicher, dass alle Interaktionen innerhalb der Architektur autorisiert und sicher sind.

Die Development Kit-Übersicht bietet einen Einblick in unsere Architektur. Weitere Informationen dazu, wie Projekte konfiguriert werden, Authentifizierungsrichtlinien und Informationen zu den ersten Schritte finden Sie in den folgenden Artikeln:

Diagramm, das zeigt, wie das Fabric SDK in Fabric integriert ist.

Das Front-End richtet die Kommunikation mit dem Fabric Front–End Portal über einen iFrame ein. Das Portal interagiert wiederum mit dem Fabric-Back-End, indem Aufrufe an die verfügbar gemachten öffentlichen APIs getätigt werden.

Für Interaktionen zwischen dem Back-End-Entwicklungsfeld und dem Fabric Back-End dient das Azure Relay als Verbindungsleitung. Darüber hinaus wird das Back-End-Entwicklungsfeld nahtlos in Lakehouse integriert. Die Kommunikation wird durch die Verwendung von Azure Relay und dem Fabric Software Development Kit (SDK) erleichtert, das auf der Back-End-Entwicklungsbox installiert ist.

Die Authentifizierung für alle Kommunikationen innerhalb dieser Komponenten wird über Microsoft Entra sichergestellt. Microsoft Entra bietet eine sichere und authentifizierte Umgebung für die Interaktionen zwischen Front-End, Back-End, Azure Relay, Fabric SDK und Lakehouse.

Voraussetzungen

Stellen Sie sicher, dass der NuGet Package Manager in Ihre Visual Studio-Installation integriert ist. Dieses Tool wird für die optimierte Verwaltung externer Bibliotheken und Pakete benötigt, die für unser Projekt wichtig sind.

NuGet-basierte Paketverwaltung

  • <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> und <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Diese Eigenschaften geben den Pfad zu den NuSpec-Dateien an, die zum Erstellen des NuGet-Pakets für Debug- und Releasemodi verwendet werden. Die NuSpec-Datei enthält Metadaten über das Paket, wie z. B. seine ID, Version, Abhängigkeiten und andere relevante Informationen.

  • <GeneratePackageOnBuild>true</GeneratePackageOnBuild>: Wenn diese Eigenschaft auf true gesetzt ist, weist sie den Buildprozess an, bei jedem Buildvorgang automatisch ein NuGet-Paket zu erstellen. Diese Eigenschaft ist nützlich, um sicherzustellen, dass das Paket immer auf dem neuesten Stand ist, was die letzten Änderungen im Projekt betrifft.

  • <IsPackable>true</IsPackable>: Wenn diese Eigenschaft auf true gesetzt ist, gibt sie an, dass das Projekt in ein NuGet-Paket gepackt werden kann. Dies ist eine wichtige Eigenschaft für Projekte, die während des Buildprozesses NuGet-Pakete erzeugen sollen.

Das generierte NuGet-Paket für den Debugmodus befindet sich nach dem Buildprozess im Verzeichnis src\bin\Debug.

Wenn Sie im Cloudmodus arbeiten, können Sie die Visual Studio-Buildkonfiguration auf Release umstellen und das Paket erstellen. Das generierte Paket befindet sich im Verzeichnis src\bin\Release. Weitere Informationen finden Sie im Leitfaden zum Arbeiten im Cloudmodus.

Abhängigkeiten

  • Das Back-End-Boilerplatebeispiel hängt von den folgenden Azure SDK-Paketen ab:

    • Azure.Core
    • Azure.Identity
    • Azure.Storage.Files.DataLake
    • Das Microsoft Identity Paket

Um den NuGet-Paket-Manager zu konfigurieren, geben Sie vor dem Buildprozess den Pfad im Abschnitt Paketquellen an.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
    <BuildDependsOn>PreBuild</BuildDependsOn>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <IsPackable>true</IsPackable>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.Core" Version="1.38.0" />
    <PackageReference Include="Azure.Identity" Version="1.11.0" />
    <PackageReference Include="Azure.Storage.Files.DataLake" Version="12.14.0" />
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.9" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="7.0.5" />
    <PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="7.0.0" />
    <PackageReference Include="Microsoft.Identity.Client" Version="4.60.3" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols.OpenIdConnect" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Tokens" Version="6.30.1" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Properties\ServiceDependencies\" />
  </ItemGroup>

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\RemoveErrorFile.ps1 -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXml WorkloadManifest.xml -inputXsd WorkloadDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ItemManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXsd ItemDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ValidateNoDefaults.ps1 -outputDirectory ValidationScripts\" />
    <Error Condition="Exists('ValidationScripts\ValidationErrors.txt')" Text="Validation errors with either manifests or default values" File="ValidationScripts\ValidationErrors.txt" />
  </Target>

</Project>

Erste Schritte

So richten Sie das Workloadbeispielprojekt auf dem lokalen Computer ein:

  1. Klonen Sie das Repository: Führen Sie git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git aus.

  2. Öffnen Sie die Projektmappe in Visual Studio 2022.

  3. Richten Sie eine App-Registrierung ein, indem Sie den Anweisungen im Tutorial zur Authentifizierung folgen. Vergewissern Sie sich, dass sowohl Ihr Front-End- als auch Ihr Back-End-Projekt die im Artikel beschriebene Einrichtung aufweisen. Microsoft Entra wird für die sichere Authentifizierung verwendet, um sicherzustellen, dass alle Interaktionen innerhalb der Architektur autorisiert und sicher sind.

  4. Aktualisieren Sie die DFS-Basis-URL für Microsoft OneLake. Je nach Fabric-Umgebung können Sie möglicherweise den Wert für OneLakeDFSBaseURL im Ordner src\Constants aktualisieren. Die Standardeinstellung ist onelake.dfs.fabric.microsoft.com, Sie können die URL jedoch so aktualisieren, dass sie Ihre Umgebung widerspiegelt. Weitere Informationen zu DFS-Pfaden finden Sie in der OneLake-Dokumentation.

  5. Richten Sie die Workloadkonfiguration ein.

    1. Kopieren Sie workload-dev-mode.json von src/Config nach C:.
    2. Aktualisieren Sie in der workload-dev-mode.json-Datei die folgenden Felder so, dass sie Ihrer Konfiguration entsprechen:
      • WorkspaceGuid: Ihre Arbeitsbereichs-ID. Sie finden diesen Wert in der Browser-URL, wenn Sie einen Arbeitsbereich in Fabric auswählen. Beispiel: https://app.powerbi.com/groups/<WorkspaceID>/.
      • ManifestPackageFilePath: Der Speicherort des Manifestpakets. Wenn Sie die Lösung erstellen, wird das Manifestpaket in src\bin\Debug gespeichert. Weitere Informationen zum Manifestpaket finden Sie weiter unten im Artikel.
      • WorkloadEndpointURL: Die Endpunkt-URL der Workload.
    3. Aktualisieren Sie in der Datei Packages/manifest/WorkloadManifest.xml die folgenden Felder entsprechend Ihrer Konfiguration:
      • <AppId>: Die Client-ID (Anwendungs-ID) der Microsoft Entra-Anwendung für die Workload.
      • <RedirectUri>: Die Umleitungs-URIs. Sie finden diesen Wert in der App-Registrierung, die Sie erstellt haben, unter Authentifizierung.
      • <ResourceId>: Die Zielgruppe für eingehende Microsoft Entra-Token. Diese Information finden Sie in Ihrer App-Registrierung, die Sie unter Verfügbarmachen einer API erstellt haben.
    4. Aktualisieren Sie in der src/appsettings.json-Datei die folgenden Felder so, dass sie Ihrer Konfiguration entsprechen:
      • PublisherTenantId: Die ID des Arbeitsauslastungs-Herausgebermandanten.
      • ClientId: Die Client-ID (Anwendungs-ID) der Microsoft Entra-Anwendung der Workload.
      • ClientSecret: Der geheime Schlüssel für die Workload Microsoft Entra-Anwendung.
      • Audience: Die Zielgruppe für eingehende Microsoft Entra-Token. Diese Information finden Sie in Ihrer App-Registrierung, die Sie unter Verfügbarmachen einer API erstellt haben. Diese Einstellung wird auch als Anwendungs-ID-URI bezeichnet.

  6. Generieren Sie ein Manifestpaket.

    Um eine Manifestpaketdatei zu generieren, erstellen Sie Fabric_Extension_BE_Boilerplate. Der Buildvorgang ist ein dreistufiger Prozess, um die Manifestpaketdatei zu generieren. Dabei werden diese Schritte ausgeführt:

    1. Löst ManifestValidator.ps1 für WorkloadManifest.xml in Packages\manifest/ aus und löst ItemManifestValidator.ps1 für alle Element-XMLs (z. B. Item1.xml) in Packages\manifest/ aus. Wenn die Validierung fehlschlägt, wird eine Fehlerdatei generiert. Sie können die Validierungsskripts in ValidationScripts/ anzeigen.
    2. Wenn eine Fehlerdatei vorhanden ist, schlägt der Buildvorgang mit dem Fehler Validierungsfehler mit Manifesten oder Standardwerten fehl. Um die Fehlerdatei in Visual Studio anzuzeigen, doppelklicken Sie in den Validierungsergebnissen auf den Fehler.
    3. Nach erfolgreicher Validierung packen Sie die Dateien WorkloadManifest.xml und Item1.xml in ManifestPackage.1.0.0.nupkg. Das resultierende Paket befindet sich in "src\bin\Debug".

    Kopieren Sie die ManifestPackage.1.0.0.nupkg-Datei in den Pfad, der in der Konfigurationsdatei workload-dev-mode.json definiert ist.

  7. Program.cs dient als Einstiegspunkt und Startskript für Ihre Anwendung. In dieser Datei können Sie verschiedene Dienste konfigurieren, die Anwendung initialisieren und den Webhost starten.

  8. Builden, um sicherzustellen, dass Ihr Projekt auf die erforderlichen Abhängigkeiten für die Kompilierung und Ausführung zugreifen kann.

  9. Herunterladen des DevGateway über das Microsoft Download Center

  10. Führen Sie die Anwendung Microsoft.Fabric.Workload.DevGateway.exe aus, und melden Sie sich mit einem Benutzer an, der über Administratorrechte für den Arbeitsbereich verfügt, der im Feld WorkspaceGuid von „workload-dev-mode.json“ angegeben ist.

    Screenshot der Microsoft-Anmeldeseite.

    Nach der Authentifizierung stellen externe Workloads die Kommunikation mit dem Fabric-Back-End über Azure Relay her. Dieser Prozess umfasst die Relay-Registrierung und die Verwaltung der Kommunikation, die von einem designierten Proxyknoten unterstützt wird. Das Paket, das das Workloadmanifest enthält, wird hochgeladen und veröffentlicht.

    In dieser Phase erkennt Fabric die Workload und integriert die zugeordnete Kapazität.

    Die Überwachung auf potenzielle Fehler ist in der Konsole möglich.

    Wenn keine Fehler angezeigt werden, ist die Verbindung hergestellt, die Registrierung erfolgreich durchgeführt und das Workloadmanifest systematisch hochgeladen worden.

    Screenshot des Ladens der Verbindung ohne Fehler.

  11. Ändern Sie das Startprojekt in Visual Studio in das Boilerplateprojekt, und wählen Sie Ausführen aus.

    Screenshot der Benutzeroberfläche des Startprojekts in Visual Studio.

Arbeiten mit dem Boilerplate-Beispielprojekt

Codegenerierung

Wir verwenden das Workload-Boilerplatebeispiel zu C# ASP.NET Core, um zu demonstrieren, wie Sie eine Workload mit REST-APIs erstellen. Das Beispiel beginnt mit dem Generieren von Serverstubs und Vertragsklassen basierend auf der Swagger-Spezifikation der Workload-API. Sie können den Code mithilfe mehrerer Swagger-Codegenerierungstools generieren. Das Boilerplatebeispiel verwendet NSwag. Das Beispiel enthält das Befehlszeilenskript GenerateServerStub.cmd, das den NSwag-Codegenerator umschließt. Das Skript verwendet einen einzelnen Parameter, bei dem es sich um einen vollständigen Pfad zum NSwag-Installationsverzeichnis handelt. Außerdem wird überprüft, ob die Swagger-Definitionsdatei (swagger.json) und die Konfigurationsdatei (nswag.json) im Ordner vorhanden sind.

Wenn Sie dieses Skript ausführen, wird eine C#-Datei mit dem Namen WorkloadAPI_Generated.cs erstellt. Der Inhalt dieser Datei kann logisch in drei Teile unterteilt werden, wie in den nächsten Abschnitten erläutert.

ASP.NET Core-Stubcontroller

Die ItemLifecycleController- und die JobsController-Klasse sind schlanke Implementierungen von ASP.NET Core-Controllern für zwei Teilmengen der Workload-API: Elementlebenszyklusverwaltung und Aufträge. Diese Klassen sind in die ASP.NET Core-HTTP-Pipeline integriert. Sie dienen als Einstiegspunkte für die API-Methoden, die in der Swagger-Spezifikation definiert sind. Diese Klassen leiten die Aufrufe an die „echte“ Implementierung weiter, die von der Workload bereitgestellt wird.

Hier ist ein Beispiel für die CreateItem-Methode:

/// <summary>
/// Called by Microsoft Fabric for creating a new item.
/// </summary>
/// <remarks>
/// Upon item creation Fabric performs some basic validations, creates the item with 'provisioning' state and calls this API to notify the workload. The workload is expected to perform required validations, store the item metadata, allocate required resources, and update the Fabric item metadata cache with item relations and ETag. To learn more see [Microsoft Fabric item update flow](https://updateflow).
/// <br/>
/// <br/>This API should accept [SubjectAndApp authentication](https://subjectandappauthentication).
/// <br/>
/// <br/>##Permissions
/// <br/>Permissions are checked by Microsoft Fabric.
/// </remarks>
/// <param name="workspaceId">The workspace ID.</param>
/// <param name="itemType">The item type.</param>
/// <param name="itemId">The item ID.</param>
/// <param name="createItemRequest">The item creation request.</param>
/// <returns>Successfully created.</returns>
[Microsoft.AspNetCore.Mvc.HttpPost, Microsoft.AspNetCore.Mvc.Route("workspaces/{workspaceId}/items/{itemType}/{itemId}")]
public System.Threading.Tasks.Task CreateItem(System.Guid workspaceId, string itemType, System.Guid itemId, [Microsoft.AspNetCore.Mvc.FromBody] CreateItemRequest createItemRequest)
{

 return _implementation.CreateItemAsync(workspaceId, itemType, itemId, createItemRequest);
}

Schnittstellen für die Workload-Implementierung

IItemLifecycleController und IJobsController sind Schnittstellen für die zuvor erwähnten „echten“ Implementierungen. Sie definieren die gleichen Methoden, die die Controller implementieren.

Definition von Vertragsklassen

C#-Vertragsklassen sind Klassen, die von den APIs verwendet werden.

Implementierung

Der nächste Schritt nach dem Generieren von Code implementiert die Schnittstellen IItemLifecycleController und IJobsController. Im Boilerplatebeispiel implementieren ItemLifecycleControllerImpl und JobsControllerImpl diese Schnittstellen.

Dieser Code ist beispielsweise die Implementierung der CreateItem-API:

/// <inheritdoc/>
public async Task CreateItemAsync(Guid workspaceId, string itemType, Guid itemId, CreateItemRequest createItemRequest)
{
 var authorizationContext = await _authenticationService.AuthenticateControlPlaneCall(_httpContextAccessor.HttpContext);
 var item = _itemFactory.CreateItem(itemType, authorizationContext);
 await item.Create(workspaceId, itemId, createItemRequest);
}

Behandeln von Elementnutzdaten

Mehrere API-Methoden akzeptieren verschiedene Nutzdatentypen als Teil des Anforderungstexts oder geben sie als Teil der Antwort zurück. Beispielsweise weist CreateItemRequest die Eigenschaft creationPayload auf.

"CreateItemRequest": {
 "description": "Create item request content.",
 "type": "object",
 "additionalProperties": false,
 "required": [ "displayName" ],
 "properties": {
 "displayName": {
  "description": "The item display name.",
  "type": "string",
  "readOnly": false
 },
 "description": {
  "description": "The item description.",
  "type": "string",
  "readOnly": false
 },
 "creationPayload": {
  "description": "Creation payload specific to the workload and item type, passed by the item editor or as Fabric Automation API parameter.",
  "$ref": "#/definitions/CreateItemPayload",
  "readOnly": false
 }
 }
}

Die Typen für diese Nutzdateneigenschaften werden in der Swagger-Spezifikation definiert. Es gibt einen dedizierten Typ für jede Art von Payload. Diese Typen definieren keine spezifischen Eigenschaften und erlauben, dass eine Eigenschaft eingeschlossen werden kann.

Hier ist ein Beispiel für den CreateItemPayload-Typ:

"CreateItemPayload": {
 "description": "Creation payload specific to the workload and item type.",
 "type": "object",
 "additionalProperties": true
}

Die generierten C#-Vertragsklassen werden als partial definiert. Sie verfügen über ein Wörterbuch mit definierten Eigenschaften.

Hier sehen Sie ein Beispiel:

/// <summary>
/// Creation payload specific to the workload and item type.
/// </summary>
[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "13.20.0.0 (NJsonSchema v10.9.0.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class CreateItemPayload
{
 private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

 [Newtonsoft.Json.JsonExtensionData]
 public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
 {
  get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
  set { _additionalProperties = value; }
 }
}

Der Code kann dieses Wörterbuch zum Lesen und Zurückgeben von Eigenschaften verwenden. Ein besserer Ansatz besteht jedoch darin, bestimmte Eigenschaften mit entsprechenden Typen und Namen zu definieren. Sie können die partial-Deklaration für die generierten Klassen verwenden, um Eigenschaften effizient zu definieren.

Die Datei CreateItemPayload.cs enthält z. B. eine ergänzende Definition für die CreateItemPayload-Klasse.

In diesem Beispiel fügt die Definition die Eigenschaft Item1Metadata hinzu:

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    /// <summary>
    /// Extend the generated class by adding item-type-specific fields.
    /// In this sample every type will have a dedicated property. Alternatively, polymorphic serialization could be used.
    /// </summary>
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }
    }
}

Wenn die Workload jedoch mehrere Elementtypen unterstützt, muss die CreateItemPayload-Klasse unterschiedliche Typen der Erstellungsnutzdaten verarbeiten können, einen pro Elementtyp. Sie haben zwei Möglichkeiten. Die einfachere Methode, die im Boilerplatebeispiel verwendet wird, besteht darin, mehrere optionale Eigenschaften zu definieren, die jeweils die Erstellungsnutzdaten für einen anderen Elementtyp darstellen. Jede Anforderung hat dann nur einen dieser Eigenschaftensätze, entsprechend dem zu erstellenden Elementtyp. Alternativ können Sie die polymorphe Serialisierung implementieren, aber diese Option wird nicht im Beispiel veranschaulicht, da sie keine wesentlichen Vorteile bietet.

Um beispielsweise zwei Elementtypen zu unterstützen, muss die Klassendefinition wie im folgenden Beispiel erweitert werden:

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }

        [Newtonsoft.Json.JsonProperty("item2Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item2Metadata Item2Metadata { get; init; }
    } 
}

Hinweis

Die an die Workload gesendeten Nutzdaten werden vom Client generiert. Dies könnte der Element-Editor-iFrame oder die Fabric Automation REST-API sein. Der Client ist dafür verantwortlich, die richtige Payload zu senden und dem Elementtyp zuzuordnen. Die Workload ist für die Überprüfung verantwortlich. Fabric behandelt diese Payload als undurchsichtiges Objekt und überträgt sie nur vom Client an die Workload. Ebenso ist es für Nutzdaten, die von der Workload an den Client zurückgegeben werden, die Verantwortung von Workload und Client, die Nutzdaten korrekt zu verarbeiten.

Dieser Code zeigt beispielsweise, wie die Implementierung von item1 im Boilerplatebeispiel die Nutzdaten behandelt:

protected override void SetDefinition(CreateItemPayload payload)
{
 if (payload == null)
 {
  Logger.LogInformation("No payload is provided for {0}, objectId={1}", ItemType, ItemObjectId);
  _metadata = Item1Metadata.Default.Clone();
  return;
 }

 if (payload.Item1Metadata == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId);
 }

 if (payload.Item1Metadata.Lakehouse == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId)
   .WithDetail(ErrorCodes.ItemPayload.MissingLakehouseReference, "Missing Lakehouse reference");
 }

 _metadata = payload.Item1Metadata.Clone();
}

Problembehandlung und Debuggen

In den nächsten Abschnitten werden Problembehandlung und Debuggen für Ihre Bereitstellung beschrieben.

Bekannte Probleme und Lösungen

Hier erhalten Sie Informationen zu bekannten Problemen und Methoden, um sie zu beheben.

Fehlen des geheimen Clientschlüssels

Fehler:

Microsoft.Identity.Client.MsalServiceException: Ein Konfigurationsproblem verhindert die Authentifizierung. Überprüfen Sie die Fehlermeldung des Servers auf Einzelheiten. Sie können die Konfiguration im Portal zur Anwendungsregistrierung ändern. Einzelheiten dazu finden Sie unter https://aka.ms/msal-net-invalid-client.

Abweichung vom Original: AADSTS7000215: Es wurde ein ungültiger geheimer Clientschlüssel angegeben. Stellen Sie sicher, dass es sich bei dem in der Anforderung gesendeten Geheimnis um den Wert des geheimen Clientschlüssels handelt, nicht um die ID des geheimer Clientschlüssels für ein Geheimnis, das der app_guid-Einstellung der App hinzugefügt wurde.

Lösung: Stellen Sie sicher, dass Sie den richtigen geheimen Clientschlüssel in appsettings.json definiert haben.

Fehler:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Der Benutzer oder Administrator hat nicht zugestimmt, die Anwendung mit der ID <example ID> zu verwenden. Send an interactive authorization request for this user and resource. (Senden Sie eine interaktive Autorisierungsanforderung für diesen Benutzer und die Ressource.)

Lösung:

  1. Navigieren Sie im Element-Editor nach unten, und wählen Sie Zur Authentifizierungsseite navigieren aus.

  2. Geben Sie unter Bereiche den Wert .default ein, und wählen Sie Zugriffstoken abrufen aus.

  3. Genehmigen Sie im Dialogfeld die Überarbeitung.

Die Artikel-Erstellung schlägt aufgrund der Kapazitätsauswahl fehl

Fehler:

PriorityPlacement: Für die Prioritätsplatzierung stehen keine Kerndienste zur Verfügung. Nur name, guidund workload-name sind verfügbar.

Lösung:

Als Benutzer haben Sie möglicherweise nur Zugriff auf die Testkapazität. Stellen Sie sicher, dass Sie eine Kapazität verwenden, auf die Sie Zugriff haben.

Fehler beim Erstellen von Dateien mit 404 (NotFound)-Fehler

Fehler:

Fehler beim Erstellen einer neuen Datei für filePath: 'workspace-id'/'lakehouse-id'/Files/data.json. Der Statuscode der Antwort gibt keinen Erfolg an: 404 (NotFound).

Lösung:

Stellen Sie sicher, dass Sie mit der OneLake DFS-URL arbeiten, die zu Ihrer Umgebung passt. Wenn Sie zum Beispiel mit einer PPE-Umgebung arbeiten, ändern Sie EnvironmentConstants.OneLakeDFSBaseUrl in Constants.cs in die entsprechende URL.

Debug

Wenn Sie Fehler bei verschiedenen Vorgängen beheben, können Sie Haltepunkte im Code festlegen, um das Verhalten zu analysieren und zu debuggen. Führen Sie zum effektiven Debuggen die folgenden Schritte aus:

  1. Öffnen Sie den Code in Ihrer Entwicklungsumgebung.
  2. Navigieren Sie zu der entsprechenden Operationshandlerfunktion (z. B. OnCreateFabricItemAsync für CRUD-Vorgänge oder einen Endpunkt in einem Controller für execute-Vorgänge).
  3. Setzen Sie Haltepunkte an jenen Zeilen, an denen Sie den Code untersuchen möchten.
  4. Ausführen der Anwendung im Debugmodus
  5. Lösen Sie den Vorgang vom Front-End aus, den Sie debuggen möchten.

Der Debugger hält die Ausführung an den angegebenen Haltepunkten an und ermöglicht es Ihnen, Variablen zu untersuchen, durch den Code zu gehen und Probleme zu ermitteln.

Screenshot des Beispielprogramms mit Haltepunkten für das Debuggen.

Arbeitsbereich

Wenn Sie ein Back-End mit dem Beispielworkloadprojekt verbinden, muss Ihr Element zu einem Arbeitsbereich gehören, der einer Kapazität zugeordnet ist. Standardmäßig ist der Arbeitsbereich Mein Arbeitsbereich nicht mit einer Kapazität verknüpft. Andernfalls erhalten Sie möglicherweise den Fehler, der im folgenden Screenshot angezeigt wird:

Screenshot der Benutzeroberfläche zum Benennen eines Beispielworkloadelements.

  1. Wechseln Sie zu einem benannten Arbeitsbereich. Behalten Sie den Standardarbeitsbereichsnamen Mein Arbeitsbereich bei.

    Screenshot der Benutzeroberfläche zum Erstellen von Beispielworkloads.

  2. Laden Sie die Beispielworkload aus dem richtigen Arbeitsbereich, und fahren Sie mit den Tests fort:

    Screenshot der Benutzeroberfläche zum Erstellen eines Beispielworkloadelements.

Mitwirken

Wir begrüßen Beiträge zu diesem Projekt. Wenn Sie Probleme feststellen oder neue Features hinzufügen möchten, führen Sie die folgenden Schritte aus:

  1. Forke das Repository.
  2. Erstellen Sie einen neuen Zweig für Ihre Feature oder Programmfehlerbehebung.
  3. Nehmen Sie Ihre Änderungen vor und committen Sie sie.
  4. Übertragen Sie Ihre Änderungen in Ihr geforktes Repository.
  5. Erstellen Sie einen Pull Request mit einer klaren Beschreibung Ihrer Änderungen.

Zugehöriger Inhalt