Bagikan melalui

Plugin lintas platform NuGet

Di NuGet 4.8+ dukungan untuk plugin lintas platform telah ditambahkan. Ini dicapai dengan membangun model ekstensibilitas plugin baru, yang harus sesuai dengan serangkaian aturan operasi yang ketat. Plugin-plugin adalah executable mandiri (runnable dalam ekosistem .NET Core) yang diluncurkan oleh Klien NuGet dalam proses yang terpisah. Ini adalah plugin yang ditulis sekali, dapat dijalankan di mana saja. Ini akan bekerja dengan semua alat klien NuGet. Plugin dapat ditulis dalam bahasa pemrograman apa pun, tetapi pengembangan plugin dan pengalaman penginstalan yang paling mudah akan dilakukan dengan .NET. Protokol komunikasi versi antara Klien NuGet dan plugin ditentukan. Selama jabat tangan startup, 2 proses menegosiasikan versi protokol.

Bagaimana cara kerjanya

Alur kerja tingkat tinggi dapat dijelaskan sebagai berikut:

  1. NuGet menemukan plugin yang tersedia.
  2. Jika berlaku, NuGet akan melakukan iterasi atas plugin dalam urutan prioritas dan memulainya satu per satu.
  3. NuGet akan menggunakan plugin pertama yang dapat melayani permintaan.
  4. Plugin akan dimatikan ketika tidak lagi diperlukan.

Persyaratan plugin umum

Versi protokol saat ini adalah 2.0.0. Di bawah versi ini, persyaratannya adalah sebagai berikut:

  • Mendukung peluncuran stateless dalam konteks keamanan alat klien NuGet saat ini. Misalnya, alat klien NuGet tidak akan melakukan elevasi atau inisialisasi tambahan di luar protokol plugin yang dijelaskan nanti.
  • Jangan interaktif, kecuali ditentukan secara eksplisit.
  • Patuhi versi protokol plugin yang dinegosiasikan.
  • Menanggapi semua permintaan dalam periode waktu yang wajar.
  • Menghormati permintaan pembatalan untuk setiap operasi yang sedang berlangsung.

Plugin yang ditemukan dari variabel lingkungan PATH (misalnya, diinstal melalui dotnet tool) selain itu harus cocok dengan pola nuget-plugin-*nama file . Bagian nuget-plugin- harus ditulis sepenuhnya dalam huruf kecil.

NuGet 6.12 (MSBuild 17.12, dan .NET SDK 9.0.100) dan yang lebih lama juga memerlukan plugin untuk ditandatangani Authenticode di Windows.

Spesifikasi teknis dijelaskan secara lebih rinci dalam spesifikasi berikut:

Pengguna - Interaksi Plugin

Alat klien NuGet dan plugin berkomunikasi dengan JSON melalui aliran standar (stdin, stdout, stderr). Semua data harus dikodekan UTF-8. Plugin diluncurkan dengan argumen "-Plugin". Jika pengguna secara langsung meluncurkan plugin yang dapat dieksekusi tanpa argumen ini, plugin dapat memberikan pesan informatif alih-alih menunggu jabat tangan protokol. Batas waktu jabat tangan protokol adalah 5 detik. Plugin harus menyelesaikan pengaturan sesingkat mungkin. Alat klien NuGet akan mengkueri operasi plugin yang didukung dengan meneruskan indeks layanan untuk sumber NuGet. Plugin dapat menggunakan indeks layanan untuk memeriksa keberadaan jenis layanan yang didukung.

Komunikasi antara alat klien NuGet dan plugin bersifat dua arah. Setiap permintaan memiliki batas waktu 5 detik. Jika operasi seharusnya memakan waktu lebih lama, proses masing-masing harus mengirimkan pesan kemajuan untuk mencegah permintaan kehabisan waktu. Setelah 1 menit tidak aktif, plugin dianggap menganggur dan dimatikan.

Penginstalan dan penemuan plugin

NuGet mencari plugin dari struktur direktori berbasis konvensi, dan memindai variabel lingkungan PATH.

Penemuan berbasis konvensi

Skenario CI/CD dan pengguna daya dapat menggunakan variabel lingkungan untuk mengambil alih perilaku. Saat menggunakan variabel lingkungan, hanya jalur absolut yang diizinkan. Perhatikan bahwa NUGET_NETFX_PLUGIN_PATHS dan NUGET_NETCORE_PLUGIN_PATHS hanya tersedia dengan versi 5.3+ alat NuGet dan yang lebih baru.

  • NUGET_NETFX_PLUGIN_PATHS - mendefinisikan plugin yang akan digunakan oleh alat berbasis .NET Framework (NuGet.exe/MSBuild.exe/ Visual Studio). Lebih diutamakan daripada NUGET_PLUGIN_PATHS. (Hanya NuGet versi 5.3+)
  • NUGET_NETCORE_PLUGIN_PATHS - mendefinisikan plugin yang akan digunakan oleh alat berbasis .NET Core (dotnet.exe). Lebih diutamakan daripada NUGET_PLUGIN_PATHS. (Hanya NuGet versi 5.3+)
  • NUGET_PLUGIN_PATHS - mendefinisikan plugin yang akan digunakan untuk proses NuGet tersebut, prioritas dipertahankan. Jika variabel lingkungan ini diatur, variabel tersebut akan mengambil alih penemuan berbasis konvensi. Diabaikan jika salah satu atau kedua variabel khusus kerangka kerja ditetapkan.
  • Lokasi pengguna, lokasi NuGet Home di %UserProfile%/.nuget/plugins. Lokasi ini tidak dapat diubah. Direktori akar yang berbeda akan digunakan untuk plugin .NET Core dan .NET Framework.
Kerangka kerja Lokasi penemuan akar Digunakan oleh
.NET Core %UserProfile%/.nuget/plugins/netcore dotnet CLI (antarmuka baris perintah)
.NET Framework %UserProfile%/.nuget/plugins/netfx MSBuild, NuGet.exe, Visual Studio

Setiap plugin harus diinstal di foldernya sendiri. Titik entri plugin akan menjadi nama folder yang diinstal, dengan ekstensi .dll untuk .NET Core, dan ekstensi .exe untuk .NET Framework.

.nuget
    plugins
        netfx
            myPlugin
                myPlugin.exe
                nuget.protocol.dll
                ...
        netcore
            myPlugin
                myPlugin.dll
                nuget.protocol.dll
                ...

Penemuan PATH

Mulai dari NuGet 6.13, NuGet akan mencari setiap direktori yang disediakan dalam variabel lingkungan PATH untuk file yang cocok dengan pola nuget-plugin-*. Pencocokan pola sensitif terhadap huruf besar/kecil, dan nuget-plugin- harus ditulis sepenuhnya dalam huruf kecil. Pada Windows, file harus memiliki .exe ekstensi atau .bat . Di Linux dan Mac, file harus memiliki bit yang dapat dieksekusi yang disetel.

Ini memungkinkan plugin NuGet diinstal melalui dotnet tool perintah, WinGet, manajer paket distribusi Linux, atau metode lain yang dapat menempatkan executable pada PATH pengguna. Ini juga memungkinkan plugin NuGet ditulis dalam bahasa pemrograman apa pun (sebelumnya plugin untuk Linux dan Mac harus ditulis dalam .NET).

Kami merekomendasikan plugin dikembangkan di .NET, sehingga Anda dapat menggunakan paket NuGet.Protocol untuk menghindari perlu menulis kode RPC json, dan untuk memungkinkan pelanggan menemukan plugin Anda melalui dotnet package search nuget-plugin.

Operasi yang didukung

Dua operasi didukung di bawah protokol plugin baru.

Nama operasi Versi protokol minimum Minimum versi klien NuGet
Unduh Paket 1.0.0 4.3.0
Autentikasi 2.0.0 4.8.0

Menjalankan plugin di bawah runtime yang benar

Untuk NuGet dalam skenario dotnet.exe, plugin harus dapat dijalankan di bawah runtime tertentu dari dotnet.exe. Menjadi tanggung jawab penyedia plugin dan konsumen untuk menggunakan kombinasi dotnet.exe/plugin yang kompatibel. Masalah potensial dapat muncul dengan plugin lokasi pengguna ketika, misalnya, dotnet.exe di bawah runtime 2.0 mencoba menggunakan plugin yang dibuat untuk runtime 2.1.

Penyimpanan Sementara Kemampuan

Verifikasi keamanan dan instansiasi plugin mahal. Operasi pengunduhan terjadi jauh lebih sering daripada operasi autentikasi, namun rata-rata pengguna NuGet hanya cenderung memiliki plugin autentikasi. Untuk meningkatkan pengalaman, NuGet akan menyimpan klaim operasi untuk permintaan yang diberikan. Cache ini adalah per plugin dengan kunci plugin berupa jalur plugin, dan masa berlaku untuk cache kemampuan ini adalah 30 hari.

Cache terletak di %LocalAppData%/NuGet/plugins-cache dan ditimpa dengan variabel lingkungan NUGET_PLUGINS_CACHE_PATH. Untuk menghapus cache ini, seseorang dapat menjalankan perintah lokal dengan plugins-cache opsi . Opsi all lokal sekarang juga akan menghapus cache plugin.

Indeks pesan protokol

Pesan Protokol Versi 1.0.0 :

  1. Tutup

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan tidak akan berisi payload
    • Tidak ada respons yang diharapkan. Respons yang tepat adalah agar proses plugin menghentikan atau menutup dirinya sendiri dengan segera.

  2. Salin file dalam paket

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
      • jalur direktori tujuan
      • daftar file dalam paket yang akan disalin ke jalur tujuan direktori
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • enumerable jalur lengkap untuk file yang disalin di direktori tujuan jika operasi berhasil

  3. Salin file paket (.nupkg)

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
      • jalur file tujuan
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

  4. Mendapatkan kredensial

    • Petunjuk permintaan: plugin -> NuGet
    • Permintaan akan berisi:
      • lokasi repositori sumber paket
      • kode status HTTP yang diperoleh dari repositori sumber paket menggunakan kredensial saat ini
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • nama pengguna, jika tersedia
      • kata sandi, jika tersedia

  5. Mendapatkan file dalam paket

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • suatu kumpulan jalur file dalam paket jika operasi berhasil

  6. Memperoleh klaim operasi

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • layanan index.json sebagai sumber paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • Daftar operasi yang tersedia (misalnya unduhan paket) jika operasi berhasil dilakukan. Jika plugin tidak mendukung sumber paket, plugin harus mengembalikan serangkaian operasi yang didukung yang kosong.

Nota

Pesan ini telah diperbarui dalam versi 2.0.0. Pihak klien harus mempertahankan kompatibilitas mundur.

  1. Dapatkan hash paket

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
      • algoritma hash
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • hash file paket menggunakan algoritma hash yang diminta jika operasi berhasil

  2. Memperoleh versi paket

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • daftar versi paket jika operasi tersebut berhasil

  3. Mendapatkan indeks layanan

    • Petunjuk permintaan: plugin -> NuGet
    • Permintaan akan berisi:
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • indeks layanan jika operasi berhasil

  4. Jabat tangan

    • Arah permintaan: NuGet <-> plugin
    • Permintaan akan berisi:
      • versi protokol plugin saat ini
      • versi protokol plugin minimum yang didukung
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • versi protokol yang dinegosiasikan jika operasi berhasil. Kegagalan akan mengakibatkan penghentian plugin.

  5. Menginisialisasi

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • versi alat klien NuGet
      • bahasa pemrograman yang efektif dari alat klien NuGet. Ini mempertimbangkan pengaturan ForceEnglishOutput, jika digunakan.
      • batas waktu permintaan bawaan, yang memiliki prioritas lebih tinggi daripada default protokol.
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi. Kegagalan akan mengakibatkan penghentian plugin.

  6. Catatan

    • Petunjuk permintaan: plugin -> NuGet
    • Permintaan akan berisi:
      • tingkat log untuk permintaan
      • pesan untuk dicatat
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi.

  7. Memantau keluarnya proses NuGet

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID proses NuGet
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi.

  8. Paket prefetch

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

  9. Mengatur kredensial

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • lokasi repositori sumber paket
      • nama pengguna sumber paket terakhir yang diketahui, jika tersedia
      • kata sandi sumber paket terakhir yang diketahui, jika tersedia
      • nama pengguna proksi terakhir yang diketahui, jika tersedia
      • kata sandi proksi terakhir yang diketahui, jika tersedia
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

  10. Atur tingkat log

    • Permintaan arahan: NuGet -> plug-in
    • Permintaan akan berisi:
      • tingkat log bawaan
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

Pesan Protokol Versi 2.0.0

  1. Dapatkan Klaim Operasi

  • Permintaan arahan: NuGet -> plug-in

    • Permintaan akan berisi:
      • layanan index.json sebagai sumber paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • daftar operasi yang didukung jika operasi berhasil. Jika plugin tidak mendukung sumber paket, plugin harus mengembalikan serangkaian operasi yang didukung yang kosong.

    Jika indeks layanan dan sumber paket null, maka plugin dapat menjawab dengan autentikasi.

  1. Dapatkan Kredensial Autentikasi
  • Permintaan arahan: NuGet -> plug-in
  • Permintaan akan berisi:
    • Uri
    • isRetry
    • NonInteraktif
    • DapatMenampilkanDialog
  • Sebuah respons akan berisi
    • Nama pengguna
    • Kata sandi
    • Pesan
    • Daftar Jenis Autentikasi
    • Kode Respons Pesan
  • Last updated on