Príručka serverovej implementácie (Preview)

Článok
08/20/2024

Tento odkladací priestor ukážky vývoja vyťaženia služby Microsoft Fabric slúži ako východiskový bod pri vytváraní aplikácií, ktoré vyžadujú integráciu s rôznymi službami, ako aj integráciu s platformou Lakehouse. Táto príručka vám pomôže nastaviť prostredie a nakonfigurovať potrebné súčasti, aby ste mohli začať. Tento článok opisuje kľúčové súčasti a ich roly v architektúre.

Frontend

Rozhranie je miesto, kde môžete spravovať používateľské prostredie (UX) a správanie. Komunikuje s klientskym portálom služby Fabric prostredníctvom prvku iFrame, čím umožňuje bezproblémovú interakciu s používateľom. Ďalšie informácie nájdete v téme Príručka k vývoju súpravy na vyťaženie služby Fabric.

Koncový server

Koncový server uchováva údaje aj metaúdaje. Využíva operácie CRUD na vytvorenie položiek vyťaženia (WL) spolu s metaúdajmi a vykonáva úlohy na vyplnenie údajov v úložisku. Komunikácia medzi koncovým a koncovým serverom sa uskutočňuje prostredníctvom verejných rozhraní API.

Azure Relay a DevGateway

Služba Azure Relay umožňuje komunikáciu medzi lokálnym vývojovým prostredím a koncovým serverom služby Fabric počas prevádzky v režime vývoja. V režime vývojára funguje vyťaženie v počítači vývojára. Pomôcka DevGateway.exe má dve roly:

Spracováva stranu vyťaženia kanála Azure Relay a spravuje registráciu lokálnej inštancie vyťaženia so službou Fabric v kontexte konkrétnej kapacity, čím sa vyťaženie sprístupní vo všetkých pracovných priestoroch priradených k danej kapacite. Nástroj spracováva zrušenie registrácie po zastavení.
Kanály (spolu so službou Azure relay) volania rozhrania API vyťaženia zo služby Fabric do vyťaženia.

Volania rozhrania API ovládacích prvkov vyťaženia sa vykonávajú priamo z vyťaženia do služby Fabric a nevyžadujú kanál Azure Relay.

Integrácia lakehouse

Architektúra súpravy na vývoj vyťaženia je bezproblémovo integrovaná s balíkom Lakehouse a umožňuje operácie ako ukladanie, čítanie a načítavanie údajov. Interakciu uľahčuje služba Azure Relay a súprava Fabric SDK, čím sa zabezpečuje bezpečná a overovaná komunikácia. Ďalšie podrobnosti nájdete v téme Práca so zákazníckymi údajmi.

Overenie a zabezpečenie

Microsoft Entra ID sa používa na zabezpečené overovanie, pričom zabezpečuje, aby všetky interakcie v rámci architektúry boli autorizované a zabezpečené.

Prehľad vývojových súprav poskytuje náhľad do našej architektúry. Ďalšie informácie o konfigurácii projektu, pokynoch na overovanie a začiatkoch nájdete v nasledujúcich dokumentoch overenia:

Diagram znázorňujúci, ako sa služba Fabric SDK integrovala do služby Fabric.

Klientske spojenie vytvára komunikáciu s klientskym portálom služby Fabric prostredníctvom prvku iFrame. Portál zase interaguje s koncovým serverom služby Fabric tým, že volá svoje exponované verejné rozhrania API.

Na interakcie medzi koncovým vývojovým poľom a koncovým serverom služby Fabric slúži služba Azure Relay ako kanál. Navyše klientske vývojové pole sa bezproblémovo integruje s lakehouse. Komunikáciu uľahčuje služba Azure Relay a súprava Fabric Software Development Kit (SDK) nainštalovaná do serverového vývojového poľa.

Overovanie všetkých komunikácií v rámci týchto komponentov je zabezpečené prostredníctvom spoločnosti Microsoft Entra. Microsoft Entra poskytuje zabezpečené a overené prostredie na interakcie medzi klientskym, koncovým serverom, službou Azure Relay, fabric SDK a lakehouse.

Požiadavky

.NET 7.0 SDK
Visual Studio 2022

Uistite sa, že Správca balíkov NuGet je integrovaná do vašej inštalácie Visual Studia. Tento nástroj sa vyžaduje pri zjednodušenom spravovaní externých knižníc a balíkov nevyhnutných pre náš projekt.

Správa balíkov NuGet

<NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> a <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Tieto vlastnosti špecifikujú cestu k súborom NuSpec používaným na vytvorenie balíka NuGet pre režimy ladenia a vydania. Súbor NuSpec obsahuje metaúdaje o balíku, ako je napríklad jeho ID, verzia, závislosti a ďalšie relevantné informácie.
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>: Ak je nastavená hodnota true, táto vlastnosť nariaďuje procesu vytvárania automaticky vygenerovať balík NuGet počas každej zostavy. Táto vlastnosť je užitočná na zabezpečenie toho, že balík je vždy aktuálny a obsahuje najnovšie zmeny v projekte.
<IsPackable>true</IsPackable>: Keď je nastavená hodnota true, táto vlastnosť indikuje, že projekt je možné zbaliť, čo znamená, že ho možno zabaliť do balíka NuGet. Je to základná vlastnosť pre projekty určené na vytváranie balíkov NuGet počas procesu vytvárania.

Vygenerovaný balík NuGet pre režim ladenia sa nachádza v adresári src\bin\Debug po procese vytvárania. Pri práci v cloudovom režime môžete prepnúť konfiguráciu zostavy Visual Studia na položku Release a vytvoriť balík. Vygenerovaný balík sa nachádza v adresári src\bin\Release . Ďalšie informácie nájdete v téme Sprievodca prácou v cloudovom režime.

Závislosti

Serverová vzorka kotlov závisí od nasledujúcich balíkov Azure SDK:
- Azure.Core
- Azure.Identity
- Azure.Storage.Files.DataLake
- Balík microsoft identity

Ak chcete nakonfigurovať Správca balíkov NuGet, zadajte cestu pred procesom vytvárania v časti Package Sources (Zdroje balíkov).

<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>

Začíname

Ak chcete nastaviť ukážkový projekt vyťaženia v lokálnom počítači, postupujte podľa týchto krokov:

Klonovanie odkladacieho priestoru: git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git
Otvorte riešenie vo Visual Studiu 2022.
Nastavte registráciu aplikácie podľa nasledujúcich pokynov v sprievodcovi overovaním. Skontrolujte, či vaše klientske aj serverové projekty majú potrebné nastavenie popísané v príručke. Na zabezpečené overovanie sa používa služba Microsoft Entra, ktorá zabezpečuje, aby boli všetky interakcie v rámci architektúry autorizované a zabezpečené.
Aktualizujte základnú URL adresu služby OneLake DFS: V závislosti od prostredia služby Fabric môžete aktualizovať prvky v priečinku OneLakeDFSBaseURL src\Constants . Predvolená hodnota je onelake.dfs.fabric.microsoft.com , ale táto možnosť môže byť aktualizovaná tak, aby zodpovedala prostrediu, v akom sa nachádzate. Ďalšie informácie o cestách DFS nájdete v dokumentácii One Lake.
Nastavenie konfigurácie vyťaženia
- Kopírovanie workload-dev-mode.json zo stránky src/Config do C:\
- V súbore workload-dev-mode.json aktualizujte nasledujúce polia tak, aby zodpovedali vašej konfigurácii:
  - CapacityGuid: ID kapacity. Nájdete to na portáli služby Fabric v časti Nastavenia kapacity na portáli na správu.
  - ManifestPackageFilePath: Umiestnenie balíka manifestu. Pri vytváraní riešenia sa uloží balík manifestu v rámci src\bin\Debug. Ďalšie podrobnosti o balíku manifestu nájdete v ďalších krokoch.
  - WorkloadEndpointURL: URL adresa koncového bodu vyťaženia.
- V súbore Packages/manifest/WorkloadManifest.xml aktualizujte nasledujúce polia tak, aby zodpovedali vašej konfigurácii:
  - <AppId>: ID klienta (ID aplikácie) vyťaženia aplikácie Microsoft Entra.
  - <Identifikátor RedirectUri>: Identifikátory URI presmerovania. Nájdete to v registrácii aplikácie, ktorú ste vytvorili v časti Overenie.
  - <ResourceId>: Cieľová skupina prichádzajúcich tokenov Microsoft Entra. Tieto informácie nájdete v registrácii aplikácie, ktorú ste vytvorili v časti Vystavenie rozhrania API.
- V súbore src/appsettings.json aktualizujte nasledujúce polia tak, aby zodpovedali konfigurácii:
  - PublisherTenantId: ID nájomníka vydavateľa vyťaženia.
  - ClientId: ID klienta (ID aplikácie) vyťaženia aplikácie Microsoft Entra.
  - ClientSecret: Tajný kód aplikácie Microsoft Entra pre vyťaženie.
  - Cieľová skupina: Cieľová skupina prichádzajúcich tokenov Microsoft Entra. Tieto informácie nájdete v registrácii aplikácie, ktorú ste vytvorili v časti Vystavenie rozhrania API. Nazýva sa to aj identifikátor URI ID aplikácie.
Vygenerujte balík manifestu. Ak chcete generovať súbor balíka manifestu, vytvorte Fabric_Extension_BE_Boilerplate. Spustí sa proces v troch krokoch na vygenerovanie súboru manifestu balíka:
1. WorkloadManifest.xml Spúšťanie v aplikácii ManifestValidator.ps1 *Packages\manifest* a spúšťanie ItemManifestValidator.ps1 na všetkých položkách knižnice XMLs (napríklad Item1.xml) v časti *Packages\manifest*. Ak overenie zlyhá, vygeneruje sa súbor chyby. Overovacie skripty môžete zobraziť v *ValidationScripts*.
2. Ak existuje súbor chyby, zostava zlyhá s .Validation errors with either manifests or default values Dvojitým výberom chyby vo Visual Studiu sa zobrazí súbor chyby.
3. Po úspešnom overení zbaľte WorkloadManifest.xml súbory a Item1.xml do súboru ManifestPackage.1.0.0.nupkg. Výsledný balík je v src\bin\Debug.
Skopírujte súbor ManifestPackage.1.0.0.nupkg k ceste definovanej v konfiguračnom súbore workload-dev-mode.json.
Program.cs je vstupný bod a skript pri spustení aplikácie. V tomto súbore môžete nakonfigurovať rôzne služby, inicializovať aplikáciu a spustiť webového hostiteľa.
Vytvorte zostavu, aby ste zabezpečili, že váš projekt bude mať prístup k požadovaným závislostiam kompilácie a vykonávania.
Stiahnutie DevGateway z Centra sťahovania softvéru spoločnosti Microsoft
Spustite aplikáciu Microsoft.Fabric.Workload.DevGateway.exe umiestnenú v priečinku DevGateway. Prihláste sa pomocou používateľa s oprávneniami správcu kapacity pre kapacitu, ktorú ste definovali v službe workload-dev-mode.json (CapacityGuid). Pri inicializácii vyťaženia sa zobrazí výzva na overenie.

Po overení môžu externé vyťaženia komunikovať s koncovým serverom služby Fabric prostredníctvom služby Azure Relay. Tento proces zahŕňa registráciu relé a správu komunikácie, ktorú uľahčuje určený uzol proxy. Okrem toho sa nahrá a publikuje balík obsahujúci manifest vyťaženia.

V tejto fáze má fabric vedomosti o vyťažení, ktoré zahŕňa jej vyhradenú kapacitu.

Monitorovanie potenciálnych chýb sa zobrazuje v konzole.

Ak sa nevykonajú žiadne chyby, pripojenie sa vytvorí, úspešne sa spustí registrácia a manifest vyťaženia sa nahral systematicky.
Zmeňte svoj startupový projekt vo Visual Studiu na projekt Kotleba a vyberte položku Spustiť.

Práca s prostredím Kotleba

Generovanie kódu

Na vysvetlenie spôsobu vytvorenia vyťaženia pomocou rozhrania REST API používame ukážku vyťaženia, ktorá ASP.NET core platformy C#. Začína sa generovanými stukami serverov a triedami zmlúv podľa špecifikácie Swagger rozhrania API workload. Môžete ich generovať pomocou niektorého z niekoľkých nástrojov na generovanie kódu Swagger. Naša ukážka Kotleba používa NSwag. Ukážka obsahuje GenerateServerStub.cmd skript príkazového riadka, ktorý zalomí generátor kódu NSwag. Skript má jeden parameter, čo je úplná cesta k inštalačnému adresáru NSwag. Očakáva tiež, že vedľa neho nájde súbor definície Swagger (swagger.json) a konfiguračný súbor (nswag.json).

Po spustení tohto skriptu sa vytvorí súbor v jazyku C# WorkloadAPI_Generated.cs. Obsah tohto súboru je možné logicky rozdeliť na tri časti nasledovne.

ovládače ASP.NET Core

ItemLifecycleController triedy a JobsController sú tenké implementácie ASP.NET Core radičov pre dve podmnožiny rozhrania API vyťaženia: správa životného cyklu položiek a úlohy. Tieto triedy sa pripájaujú do kanála HTTP ASP.NET Core a slúžia ako vstupné body pre metódy rozhrania API definované v špecifikácii Swagger. Tieto triedy preposiela volania "skutočnej" implementácii, ktorú poskytuje vyťaženie.

Toto je príklad metódy CreateItem :

/// <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);
}

Rozhrania na implementáciu vyťaženia

IItemLifecycleController a IJobsController sú rozhrania pre vyššie uvedené "reálne" implementácie. Definujú rovnaké metódy, ktoré prevádzkovatelia vykonávajú.

Definícia zmluvných tried

Zmluvné triedy C# používané rozhraniami API.

Implementácia

Ďalším krokom po generovaní kódu je implementácia rozhraní IItemLifecycleController a IJobsController . V ukážke ClonaNástavka, ItemLifecycleControllerImpl a JobsControllerImpl implementujú tieto rozhrania.

Tento kód je napríklad implementáciou rozhrania 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);
}

Spracovanie údajovej časti položky

Viaceré metódy rozhrania API akceptujú rôzne typy údajovej časti ako súčasť tela požiadavky alebo ich vrátia ako súčasť odpovede. Napríklad vlastnosť CreateItemRequest má vlastnosť creationPayload .

"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
	}
	}
}

Typy týchto vlastností "údajovej časti" sú definované v špecifikácii Swagger. Existuje vyhradený typ každej údajovej časti. Tieto typy nedefinujú žiadne konkrétne vlastnosti a umožňujú zahrnúť akúkoľvek vlastnosť. Toto je napríklad typ CreateItemPayload :

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

Generované zmluvné triedy jazyka C# sú definované ako čiastočné a majú slovník s vlastnosťami.

/// <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; }
	}
}

Kód môže použiť tento slovník na čítanie a vrátenie vlastností. Lepším prístupom je však definovanie konkrétnych vlastností so zodpovedajúcimi typmi a názvami. To možno ľahko dosiahnuť kvôli "čiastkovej" deklarácii na generovaných triedach.

Napríklad CreateItemPayload.cs súbor obsahuje doplnkovú definíciu pre triedu CreateItemPayload , ktorá pridáva vlastnosť Item1Metadata .

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; }
    }
}

Ak však vyťaženie podporuje viacero typov položiek, trieda CreateItemPayload musí byť schopná spracovať rôzne typy údajovej časti vytvorenia, jeden na typ položky. Existujú dva spôsoby, ako to urobiť. Jednoduchší spôsob, ktorý používa ukážka Kotleba, je definovať viaceré voliteľné vlastnosti, pričom každá predstavuje údajovú časť vytvorenia pre iný typ položky. Podľa vytvoreného typu položky má každá požiadavka len jednu z týchto množín vlastností. Prípadne by ste mohli implementovať polymorfnú serializáciu, ale nie je to znázornené v vzorke, pretože neposkytuje žiadne významné výhody.

Na podporu dvoch typov položiek by napríklad bolo potrebné rozšíriť túto definíciu triedy takto:

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; }
    }	
}

Poznámka

Údajová časť odoslaná na vyťaženie je vygenerovaná klientom. Môže to byť editor položiek iFrame alebo rozhranie REST API automatizácie tkaniny. Klient je zodpovedný za odoslanie správnej údajovej časti a zodpovedajúcu typu položky. Za overenie zodpovedá vyťaženie. Fabric považuje túto údajovú časť za nepriehľadný objekt a prenesie ju iba z klienta na vyťaženie. Podobne platí, že v prípade údajovej časti vrátenej vyťažením klientovi je zodpovednosťou vyťaženia a klienta správne spracovať údajovú časť.

Tento kód napríklad zobrazuje, ako implementácia ukážky ľubivej časti Item1 narába s tým, že:

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();
}

Riešenie problémov a ladenie

Známe problémy a riešenia

Chýbajúci tajný kľúč klienta

Chyba:

Microsoft.Identity.Client.MsalServiceException: Problém s konfiguráciou bráni overovaniam. Podrobnosti nájdete v chybovom hlásení zo servera. Konfiguráciu môžete upraviť na registračnom portáli aplikácie. Podrobnosti nájdete https://aka.ms/msal-net-invalid-client v téme .

Pôvodná výnimka: AADSTS7000215: Zadaný neplatný tajný kľúč klienta. Uistite sa, že tajný kľúč, ktorý sa odosiela v žiadosti, je hodnotou tajného kľúča klienta, nie ID tajného kľúča klienta pridaného do aplikácie "app_guid".

Riešenie: Uistite sa, že máte správny tajný kľúč klienta v appsettings.json.

Chyba:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Používateľ alebo správca neudelil súhlas na použitie aplikácie s ID.... Odošlite interaktívnu žiadosť o overenie pre tohto používateľa a zdroj.

Riešenie: V editore položiek prejdite nadol a vyberte položku Prejsť na stránku overenia. V časti Rozsahy zapíšte .default a vyberte položku Získať prístupový token. Súhlas s schválením môžete schváliť v rozbaľovacom dialógovom okne.

Vytvorenie položky zlyhá z dôvodu výberu kapacity

Chyba: PriorityPlacement: Neexistujú žiadne základné služby pre umiestnenie s prioritou iba 'názov','guid','workload-name'.

Riešenie: Možno používate používateľa, ktorý má prístup len ku skúšobnej kapacite. Uistite sa, že používate kapacitu, ku ktorej máte prístup.

Zlyhanie vytvorenia súboru s chybou 404 (NotFound)

Chyba:

Vytvorenie nového súboru zlyhalo pre súborPath: 'workspace-id'/'lakehouse-id'/Files/data.json. Chyba: Kód stavu odpovede neuvádza úspech: 404 (NotFound).

Riešenie: Uistite sa, že pracujete s URL adresou OneLake DFS, ktorá vyhovuje vášmu prostrediu. Ak napríklad pracujete s prostredím PPE, zmeňte hodnotu environmentConstants.OneLakeDFSBaseUrl v Constants.cs na príslušnú URL adresu.

Ladenie

Pri riešení rôznych operácií môžete v kóde nastaviť body prerušenia na analýzu a ladenie správania. Na efektívne ladenie použite tento postup:

Otvorte kód vo vašom vývojárskom prostredí.
Prejdite na príslušnú funkciu obslužného programu operácií (napríklad OnCreateFabricItemAsync pre operácie CRUD alebo koncový bod v radiči pre operácie Execute).
Umiestnite body prerušenia do konkrétnych riadkov, kde chcete skontrolovať kód.
Spustite aplikáciu v režime ladenia.
Operáciu spusťte z klientskeho rozhrania (FE), ktorú chcete ladiť.

Ladiaci nástroj pozastaví vykonávanie v zadaných bodoch prerušenia, čo vám umožní kontrolovať premenné, prechádzať kódom a identifikovať problémy.

Snímka obrazovky znázorňujúca ukážkový program s bodmi prerušenia na ladenie.

Pracovný priestor

Ak sa pripájate na koncový server k vzorovému vyťaženiu, uvedomte si, že položka musí patriť do pracovného priestoru, ktorý je priradený ku kapacite. Pracovný priestor Môj pracovný priestor nie je predvolene priradený ku kapacite. V opačnom prípade sa môže zobraziť táto chyba:

Snímka obrazovky znázorňujúca používateľské rozhranie s názvom vzorovej položky vyťaženia.

Prepnite na pomenovaný pracovný priestor a ponechajte predvolený môj pracovný priestor:
Zo správneho pracovného priestoru načítajte ukážku vyťaženia a pokračujte testami:

Prispieť

Príspevky do tohto projektu sú vítané. Ak nájdete nejaké problémy alebo chcete pridať nové funkcie, postupujte podľa týchto krokov:

Vetví odkladací priestor.
Vytvorte novú vetvu na opravu funkcie alebo chyby.
Vykonajte zmeny a potvrďte ich.
Presunutie zmien do svojho vetveného odkladacieho priestoru.
Vytvorte žiadosť o prijatie zmien s jasným popisom zmien.

Zdieľať cez

Príručka serverovej implementácie (Preview)

Frontend

Koncový server

Azure Relay a DevGateway

Integrácia lakehouse

Overenie a zabezpečenie

Požiadavky

Správa balíkov NuGet

Závislosti

Začíname

Práca s prostredím Kotleba

Generovanie kódu

ovládače ASP.NET Core

Rozhrania na implementáciu vyťaženia

Definícia zmluvných tried

Implementácia

Spracovanie údajovej časti položky

Riešenie problémov a ladenie

Známe problémy a riešenia

Chýbajúci tajný kľúč klienta

Vytvorenie položky zlyhá z dôvodu výberu kapacity

Zlyhanie vytvorenia súboru s chybou 404 (NotFound)

Ladenie

Pracovný priestor

Prispieť

Pripomienky

Ďalšie zdroje informácií

Zdieľať cez

Príručka serverovej implementácie (Preview)

Frontend

Koncový server

Azure Relay a DevGateway

Integrácia lakehouse

Overenie a zabezpečenie

Požiadavky

Správa balíkov NuGet

Závislosti

Začíname

Práca s prostredím Kotleba

Generovanie kódu

ovládače ASP.NET Core

Rozhrania na implementáciu vyťaženia

Definícia zmluvných tried

Implementácia

Spracovanie údajovej časti položky

Riešenie problémov a ladenie

Známe problémy a riešenia

Chýbajúci tajný kľúč klienta

Chyba pri vytváraní položky z dôvodu chýbajúceho súhlasu správcu

Vytvorenie položky zlyhá z dôvodu výberu kapacity

Zlyhanie vytvorenia súboru s chybou 404 (NotFound)

Ladenie

Pracovný priestor

Prispieť

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií