Menerapkan backend Microsoft Fabric

Repositori sampel pengembangan beban kerja Microsoft Fabric ini adalah titik awal untuk membangun aplikasi yang memerlukan integrasi dengan berbagai layanan dan untuk integrasi dengan arsitektur lakehouse. Artikel ini membantu Anda menyiapkan lingkungan dan mengonfigurasi komponen yang diperlukan untuk memulai. Artikel ini menguraikan komponen utama dan perannya dalam arsitektur.

Ujung depan

Frontend adalah tempat Anda mengelola pengalaman pengguna (UX) dan perilaku. Ini berkomunikasi dengan portal frontend Fabric melalui iFrame untuk memfasilitasi interaksi yang mulus.

Untuk informasi selengkapnya, lihat Kit Pengembangan Frontend Beban Kerja Microsoft Fabric.

Backend

Backend menyimpan data dan metadata. Ini menggunakan operasi Buat, Baca, Perbarui, dan Hapus (CRUD) untuk membuat item dan metadata beban kerja, dan menjalankan pekerjaan untuk mengisi data dalam penyimpanan. Komunikasi antara frontend dan backend dibuat melalui API publik.

Azure Relay dan DevGateway

Azure Relay memungkinkan komunikasi antara lingkungan pengembangan lokal dan backend Fabric dalam mode pengembang. Dalam mode pengembang, beban kerja beroperasi pada komputer pengembang.

Utilitas DevGateway memiliki dua peran:

  • Ini menangani aspek beban kerja dari saluran Azure Relay dan mengelola pendaftaran instans lokal beban kerja dengan Fabric dalam konteks ruang kerja tertentu. Utilitas menangani deregistrasi ketika saluran terputus.
  • Ini bekerja dengan Azure Relay untuk menyalurkan panggilan API dari Fabric ke beban kerja.

Panggilan API Kontrol Beban Kerja dilakukan langsung dari beban kerja ke Fabric. Saluran Azure Relay tidak diperlukan untuk panggilan.

Integrasi Lakehouse

Arsitektur kit pengembangan beban kerja terintegrasi dengan mulus dengan arsitektur lakehouse untuk operasi seperti menyimpan, membaca, dan mengambil data. Interaksi difasilitasi melalui Azure Relay dan Fabric SDK untuk membantu memastikan komunikasi yang aman dan terautentikasi. Untuk informasi selengkapnya, lihat bekerja dengan data pelanggan.

Autentikasi dan keamanan

ID Microsoft Entra digunakan untuk autentikasi aman, memastikan bahwa semua interaksi dalam arsitektur diotorisasi dan aman.

Gambaran umum kit pengembangan memberikan sekilas tentang arsitektur kami. Untuk informasi selengkapnya tentang bagaimana proyek dikonfigurasi, untuk panduan autentikasi, dan untuk memulai, lihat artikel berikut ini:

Diagram memperlihatkan bagaimana Fabric SDK terintegrasi dengan Fabric.

Frontend membangun komunikasi dengan portal frontend Fabric melalui iFrame. Portal pada gilirannya berinteraksi dengan backend Fabric dengan melakukan panggilan ke API publiknya yang terekspos.

Untuk interaksi antara kotak pengembangan backend dan backend Fabric, Azure Relay berfungsi sebagai saluran. Selain itu, kotak pengembangan backend terintegrasi dengan mulus dengan Lakehouse. Komunikasi difasilitasi dengan menggunakan Azure Relay dan Fabric Software Development Kit (SDK) yang diinstal pada kotak pengembangan backend.

Autentikasi untuk semua komunikasi dalam komponen ini dipastikan melalui Microsoft Entra. Microsoft Entra menyediakan lingkungan yang aman dan terautentikasi untuk interaksi antara frontend, backend, Azure Relay, Fabric SDK, dan Lakehouse.

Prasyarat

Pastikan Bahwa NuGet Package Manager diintegrasikan ke dalam penginstalan Visual Studio Anda. Alat ini diperlukan untuk pengelolaan yang lancar dari pustaka dan paket eksternal yang penting bagi proyek kami.

Manajemen paket NuGet

  • <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> dan <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Properti ini menentukan jalur ke file NuSpec yang digunakan untuk membuat paket NuGet untuk mode Debug dan Rilis. File NuSpec berisi metadata tentang paket, seperti ID, versi, dependensi, dan informasi relevan lainnya.

  • <GeneratePackageOnBuild>true</GeneratePackageOnBuild>: Ketika diatur ke true, properti ini menginstruksikan proses build untuk secara otomatis menghasilkan paket NuGet selama setiap build. Atribut ini berguna untuk memastikan bahwa paket senantiasa diperbarui dengan pembaruan terkini dalam proyek.

  • <IsPackable>true</IsPackable>: Ketika diatur ke true, properti ini menunjukkan bahwa proyek dapat dimas ke dalam paket NuGet. Dapat dikemas adalah properti penting untuk proyek yang bertujuan menghasilkan paket NuGet selama proses pembangunan.

Paket NuGet yang dihasilkan untuk mode debug terletak di direktori src\bin\Debug setelah proses build.

Saat bekerja dalam mode cloud, Anda dapat mengubah konfigurasi build Visual Studio menjadi Merilis dan membangun paket Anda. Paket yang dihasilkan terletak di src\bin\Release direktori. Untuk informasi selengkapnya, lihat Panduan bekerja dalam mode cloud.

Dependensi

  • Sampel Boilerplate backend bergantung pada paket Azure SDK berikut:

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

Untuk mengonfigurasi Pengelola Paket NuGet, tentukan jalur di bagian Sumber Paket sebelum Anda memulai proses build.

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

Mulai

Untuk menyiapkan proyek sampel beban kerja di komputer lokal Anda:

  1. Kloning repositori: Jalankan git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git.

  2. Di Visual Studio 2022, buka solusinya.

  3. Siapkan pendaftaran aplikasi dengan mengikuti instruksi dalam tutorial autentikasi. Pastikan proyek frontend dan backend Anda memiliki penyiapan yang diperlukan yang dijelaskan dalam artikel. Microsoft Entra digunakan untuk autentikasi aman untuk membantu memastikan bahwa semua interaksi dalam arsitektur diotorisasi dan aman.

  4. Perbarui URL dasar Microsoft OneLake DFS. Bergantung pada lingkungan Fabric Anda, Anda mungkin dapat memperbarui nilai di OneLakeDFSBaseURLfolder src\Constants . Defaultnya adalah onelake.dfs.fabric.microsoft.com, tetapi Anda dapat memperbarui URL untuk mencerminkan lingkungan Anda. Untuk informasi selengkapnya tentang jalur DFS, lihat dokumentasi OneLake.

  5. Siapkan konfigurasi beban kerja.

    1. Salin workload-dev-mode.json dari src/Config ke C:.
    2. Dalam file workload-dev-mode.json, perbarui bidang berikut agar sesuai dengan konfigurasi Anda:
      • WorkspaceGuid: ID ruang kerja Anda. Anda dapat menemukan nilai ini di URL browser saat memilih ruang kerja di Fabric. Contohnya,https://app.powerbi.com/groups/<WorkspaceID>/.
      • ManifestPackageFilePath: Lokasi paket manifes. Saat Anda membangun solusi, solusi menyimpan paket manifes di src\bin\Debug. Informasi selengkapnya tentang paket manifes disediakan nanti di artikel.
      • WorkloadEndpointURL: URL titik akhir beban kerja.
    3. Dalam file Packages/manifest/WorkloadManifest.xml, perbarui bidang berikut agar sesuai dengan konfigurasi Anda:
      • <AppId>: ID klien (ID Aplikasi) dari beban kerja aplikasi Microsoft Entra.
      • <RedirectUri>: URI pengalihan. Anda dapat menemukan nilai ini di pendaftaran aplikasi yang Anda buat, di bawah Autentikasi.
      • <ResourceId>: Audiens untuk token Microsoft Entra yang masuk. Anda dapat menemukan informasi ini di pendaftaran aplikasi yang Anda buat, di bawah Mengekspos API.
    4. Dalam file src/appsettings.json, perbarui bidang berikut agar sesuai dengan konfigurasi Anda:
      • PublisherTenantId: ID penyewa penerbit beban kerja.
      • ClientId: ID klien (ID Aplikasi) dari aplikasi Microsoft Entra beban kerja.
      • ClientSecret: Rahasia untuk beban kerja aplikasi Microsoft Entra.
      • Audiens: Audiens untuk token Microsoft Entra yang masuk. Anda dapat menemukan informasi ini di pendaftaran aplikasi yang Anda buat, di bawah Mengekspos API. Pengaturan ini juga disebut URI ID aplikasi.

  6. Buat paket manifes.

    Untuk menghasilkan file paket manifes, buat Fabric_Extension_BE_Boilerplate. Build adalah proses tiga langkah yang bertujuan untuk menghasilkan file paket manifes. Ini menjalankan langkah-langkah berikut:

    1. Memicu ManifestValidator.ps1 pada WorkloadManifest.xml di Packages\manifest/ dan memicu ItemManifestValidator.ps1 pada semua item XML (misalnya, Item1.xml) di Packages\manifest/. Jika validasi gagal, file kesalahan dihasilkan. Anda dapat melihat skrip validasi di ValidationScripts/.
    2. Jika ada file kesalahan, build gagal dengan kesalahan validasi terkait dengan manifes atau nilai default. Untuk melihat file kesalahan di Visual Studio, klik dua kali pada kesalahan dalam hasil validasi.
    3. Setelah validasi berhasil, kemas file WorkloadManifest.xml dan Item1.xml ke manifestPackage.1.0.0.nupkg. Paket yang dihasilkan berada di src\bin\Debug.

    Salin file ManifestPackage.1.0.0.nupkg ke jalur yang ditentukan dalam file konfigurasi workload-dev-mode.json.

  7. Program.cs adalah titik masuk dan skrip startup untuk aplikasi Anda. Dalam file ini, Anda dapat mengonfigurasi berbagai layanan, menginisialisasi aplikasi, dan memulai host web.

  8. Membangun untuk memastikan proyek Anda dapat mengakses dependensi yang diperlukan untuk kompilasi dan eksekusi.

  9. Unduh DevGateway dari Pusat Unduhan Microsoft

  10. Jalankan aplikasi Microsoft.Fabric.Workload.DevGateway.exe dan masuk dengan pengguna yang memiliki hak istimewa admin ruang kerja untuk ruang kerja yang ditentukan di WorkspaceGuid bidang workload-dev-mode.json.

    Cuplikan layar halaman masuk Microsoft.

    Setelah autentikasi, beban kerja eksternal membangun komunikasi dengan backend Fabric melalui Azure Relay. Proses ini melibatkan pendaftaran relai dan manajemen komunikasi yang difasilitasi oleh simpul proksi yang ditunjuk. Paket yang berisi manifes beban kerja diunggah dan diterbitkan.

    Pada tahap ini, Fabric mendeteksi beban kerja dan menggabungkan kapasitas yang dialokasikan.

    Anda dapat memantau potensi kesalahan di konsol.

    Jika tidak ada kesalahan yang ditampilkan, koneksi dibuat, pendaftaran berhasil dijalankan, dan manifes beban kerja diunggah secara sistematis.

    Cuplikan layar pemuatan koneksi tanpa kesalahan apa pun.

  11. Di Visual Studio, ubah proyek startup Anda ke proyek Boilerplate dan pilih Jalankan.

    Cuplikan layar UI untuk proyek startup di Visual Studio.

Bekerja dengan proyek sampel Boilerplate

Pembuatan kode

Kami menggunakan sampel Boilerplate C# ASP.NET Core untuk beban kerja guna memperagakan cara membangun beban kerja menggunakan REST API. Sampel dimulai dengan menghasilkan stub server dan kelas kontrak berdasarkan spesifikasi Workload API Swagger. Anda dapat membuat kode dengan menggunakan salah satu dari beberapa alat pembuatan kode Swagger. Sampel Boilerplate menggunakan NSwag. Sampel berisi skrip baris perintah GenerateServerStub.cmd , yang membungkus generator kode NSwag. Skrip mengambil satu parameter, yang merupakan jalur lengkap ke direktori penginstalan NSwag. Ini juga memeriksa file definisi Swagger (swagger.json) dan file konfigurasi (nswag.json) di folder.

Menjalankan skrip ini menghasilkan file C# bernama WorkloadAPI_Generated.cs. Konten file ini dapat dibagi secara logis menjadi tiga bagian seperti yang dijelaskan di bagian berikutnya.

Pengontrol stub ASP.NET Core

ItemLifecycleController dan JobsController kelas adalah implementasi tipis pengontrol ASP.NET Core untuk dua subset API Beban Kerja: manajemen siklus hidup item dan pekerjaan. Kelas-kelas ini terhubung ke alur HTTP ASP.NET Core. Mereka berfungsi sebagai titik masuk untuk metode API yang didefinisikan dalam spesifikasi Swagger. Kelas meneruskan panggilan ke implementasi "nyata" yang disediakan oleh beban kerja.

Berikut adalah contoh metode :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);
}

Antarmuka untuk implementasi beban kerja

IItemLifecycleController dan IJobsController merupakan antarmuka untuk implementasi "nyata" yang disebutkan sebelumnya. Mereka mendefinisikan metode yang sama, yang diterapkan pengontrol.

Definisi kelas kontrak

Kelas kontrak C# adalah kelas yang digunakan API.

implementasi

Langkah selanjutnya setelah menghasilkan kode adalah mengimplementasikan IItemLifecycleController antarmuka dan IJobsController . Dalam sampel Boilerplate, ItemLifecycleControllerImpl dan JobsControllerImpl terapkan antarmuka ini.

Misalnya, kode ini adalah implementasi API CreateItem:

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

Menangani muatan item

Beberapa metode API menerima berbagai jenis "payload" sebagai bagian dari isi permintaan, atau mereka mengembalikan payload sebagai bagian dari respons. Misalnya, CreateItemRequest memiliki creationPayload properti .

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

Tipe untuk properti payload ini ditetapkan dalam spesifikasi Swagger. Ada jenis khusus untuk setiap jenis payload. Jenis ini tidak menentukan properti tertentu, dan memungkinkan properti apa pun untuk disertakan.

Berikut adalah contoh jenisnya CreateItemPayload :

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

Kelas kontrak C# yang dihasilkan didefinisikan sebagai partial. Mereka memiliki kamus dengan properti yang ditentukan.

Berikut contohnya:

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

Kode dapat menggunakan kamus ini untuk membaca dan mengembalikan properti. Namun, pendekatan yang lebih baik adalah menentukan properti tertentu dengan menggunakan jenis dan nama yang sesuai. Anda dapat menggunakan partial deklarasi pada kelas yang dihasilkan untuk menentukan properti secara efisien.

Misalnya, file CreateItemPayload.cs berisi definisi pelengkap untuk CreateItemPayload kelas .

Dalam contoh ini, definisi menambahkan Item1Metadata properti :

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

Namun, jika beban kerja mendukung beberapa jenis item, kelas CreateItemPayload harus dapat menangani berbagai jenis payload pembuatan, satu untuk setiap jenis item. Anda memiliki dua opsi. Cara yang lebih sederhana, yang digunakan dalam sampel Boilerplate, adalah menentukan beberapa properti opsional, masing-masing mewakili payload pembuatan untuk jenis item yang berbeda. Setiap permintaan kemudian hanya memiliki salah satu set properti ini, sesuai dengan jenis item yang dibuat. Atau, Anda dapat menerapkan serialisasi polimorfik, tetapi opsi ini tidak ditunjukkan dalam sampel karena opsi tidak memberikan manfaat signifikan.

Misalnya, untuk mendukung dua jenis item, definisi kelas harus diperluas seperti dalam contoh berikut:

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

Catatan

Payload yang dikirim ke beban kerja dihasilkan oleh klien. Ini bisa menjadi editor item iFrame atau Fabric Automation REST API. Klien bertanggung jawab untuk mengirim payload yang benar dan mencocokkan jenis item. Beban kerja bertanggung jawab atas verifikasi. Fabric memperlakukan payload ini sebagai objek buram dan hanya mentransfernya dari klien ke beban kerja. Demikian pula, untuk payload yang dikembalikan oleh beban kerja kepada klien, beban kerja dan klien bertanggung jawab untuk menangani payload dengan benar.

Misalnya, kode ini menunjukkan bagaimana implementasi item1 sampel Boilerplate menangani payload.

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

Memecahkan masalah serta men-debug

Bagian berikutnya menjelaskan cara memecahkan masalah dan melakukan debug pada deployment Anda.

Masalah dan resolusi yang diketahui

Dapatkan informasi tentang masalah dan cara yang diketahui untuk mengatasinya.

Rahasia klien hilang

Kesalahan:

Microsoft.Identity.Client.MsalServiceException: Masalah konfigurasi mencegah autentikasi. Periksa pesan kesalahan dari server untuk detailnya. Anda dapat mengubah konfigurasi di portal pendaftaran aplikasi. Lihat https://aka.ms/msal-net-invalid-client untuk detailnya.

Pengecualian asli: AADSTS7000215: Rahasia klien yang tidak valid disediakan. Pastikan bahwa rahasia yang dikirim dalam permintaan adalah nilai rahasia klien dan bukan ID rahasia klien untuk rahasia yang ditambahkan ke pengaturan aplikasi app_guid .

Resolusi: Pastikan Anda memiliki rahasia klien yang benar yang ditentukan dalam appsettings.json.

Kesalahan:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Pengguna atau administrator tidak menyetujui untuk menggunakan aplikasi dengan ID <example ID>. Kirim permintaan otorisasi interaktif untuk pengguna dan sumber daya ini.

Resolusi:

  1. Di editor item, buka bagian bawah panel dan pilih Navigasi ke Halaman Autentikasi.

  2. Di bawah Cakupan, masukkan .default, lalu pilih Dapatkan Token Akses.

  3. Dalam dialog, setujui revisi.

Pembuatan item gagal karena penentuan kapasitas

Kesalahan:

PriorityPlacement: Tidak ada layanan inti yang tersedia untuk penempatan prioritas. Hanya name, guid, dan workload-name yang tersedia.

Resolusi:

Sebagai pengguna, Anda mungkin hanya memiliki akses ke kapasitas Uji Coba. Pastikan Anda menggunakan kapasitas yang dapat Anda akses.

Kegagalan pembuatan file dengan kesalahan 404 (NotFound)

Kesalahan:

Gagal membuat file baru untuk filePath: 'workspace-id'/'lakehouse-id'/Files/data.json. Kode status respons tidak menunjukkan keberhasilan: 404 (NotFound).

Resolusi:

Pastikan Anda bekerja dengan URL OneLake DFS yang sesuai dengan lingkungan Anda. Misalnya, jika Anda bekerja dengan lingkungan PPE, ubah EnvironmentConstants.OneLakeDFSBaseUrl di Constants.cs ke URL yang sesuai.

Debug

Saat memecahkan masalah berbagai operasi, Anda dapat mengatur titik henti dalam kode untuk menganalisis dan men-debug perilaku. Ikuti langkah-langkah ini untuk debug yang efektif:

  1. Buka kode di lingkungan pengembangan Anda.
  2. Buka fungsi handler operasi yang relevan (misalnya, OnCreateFabricItemAsync untuk operasi CRUD atau endpoint di pengontrol untuk operasi execute).
  3. Tempatkan titik henti pada baris tertentu tempat Anda ingin memeriksa kode.
  4. Jalankan aplikasi dalam mode debug.
  5. Picu operasi dari frontend yang ingin Anda debug.

Debugger menjeda eksekusi pada titik henti yang ditentukan sehingga Anda dapat memeriksa variabel, menelusuri kode, dan mengidentifikasi masalah.

Cuplikan layar program sampel dengan breakpoint untuk debugging.

Ruang kerja

Jika Anda menyambungkan backend ke proyek beban kerja sampel, item Anda harus termasuk dalam ruang kerja yang dikaitkan dengan kapasitas tertentu. Secara bawaan, Ruang Kerja Saya tidak terkait dengan kapasitas. Jika tidak, Anda mungkin mendapatkan kesalahan yang ditampilkan dalam cuplikan layar berikut:

Cuplikan layar UI untuk penamaan item beban kerja sampel.

  1. Beralih ke ruang kerja dengan nama. Biarkan nama workspace bawaan Ruang kerja saya.

  2. Dari ruang kerja yang benar, muat beban kerja sampel dan lanjutkan dengan pengujian:

Berikan kontribusi

Kami menyambut kontribusi untuk proyek ini. Jika Anda menemukan masalah atau ingin menambahkan fitur baru, ikuti langkah-langkah berikut:

  1. Fork repositori.
  2. Buat cabang baru untuk fitur atau perbaikan bug Anda.
  3. Buat perubahan Anda, lalu terapkan.
  4. Dorong perubahan Anda ke repositori fork Anda.
  5. Buat permintaan pull yang memiliki deskripsi yang jelas tentang perubahan Anda.

Konten terkait

  • Last updated on