Bagikan melalui

Plugin lintas platform NuGet

  • Artikel

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 adalah executable mandiri (runnable di dunia .NET Core), yang diluncurkan Klien NuGet dalam proses terpisah. Ini adalah penulisan yang benar sekali, jalankan di mana-mana plugin. Ini akan bekerja dengan semua alat klien NuGet. Plugin dapat berupa .NET Framework (NuGet.exe, MSBuild.exe dan Visual Studio), atau .NET Core (dotnet.exe). Protokol komunikasi versi antara Klien NuGet dan plugin ditentukan. Selama jabat tangan startup, 2 proses menegosiasikan versi protokol.

Untuk mencakup semua skenario alat klien NuGet, seseorang akan memerlukan .NET Framework dan plugin .NET Core. Di bawah ini menjelaskan kombinasi klien/kerangka kerja plugin.

Alat klien Kerangka
Visual Studio .NET Framework
dotnet.exe .NET Core
NuGet.exe .NET Framework
MSBuild.exe .NET Framework
NuGet.exe pada Mono .NET Framework

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:

  • Memiliki rakitan tanda tangan Authenticode yang valid dan tepercaya yang akan berjalan pada Windows dan Mono. Belum ada persyaratan kepercayaan khusus untuk rakitan yang berjalan di Linux dan Mac. Masalah yang relevan
  • Mendukung peluncuran stateless di bawah 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.

Spesifikasi teknis dijelaskan secara lebih rinci dalam spesifikasi berikut:

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

Plugin akan ditemukan melalui struktur direktori 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 variabel khusus kerangka kerja ditentukan.
  • Lokasi pengguna, lokasi NuGet Home di %UserProfile%/.nuget/plugins. Lokasi ini tidak dapat ditimpa. Direktori akar yang berbeda akan digunakan untuk plugin .NET Core dan .NET Framework.
Kerangka Lokasi penemuan akar
.NET Core %UserProfile%/.nuget/plugins/netcore
.NET Framework %UserProfile%/.nuget/plugins/netfx

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

Catatan

Saat ini tidak ada cerita pengguna untuk penginstalan plugin. Ini semederh memindahkan file yang diperlukan ke lokasi yang telah ditentukan.

Operasi yang didukung

Dua operasi didukung di bawah protokol plugin baru.

Nama operasi Versi protokol minimum Versi klien NuGet minimum
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. Ada di penyedia plugin dan konsumen untuk memastikan kombinasi dotnet.exe/plugin yang kompatibel digunakan. Potensi masalah dapat muncul dengan plugin lokasi pengguna ketika misalnya, dotnet.exe di bawah runtime 2.0 mencoba menggunakan plugin yang ditulis untuk runtime 2.1.

Penembolokan 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 menjadi jalur plugin, dan kedaluwarsa untuk cache kemampuan ini adalah 30 hari.

Cache terletak di %LocalAppData%/NuGet/plugins-cache dan ditimpa dengan variabel NUGET_PLUGINS_CACHE_PATHlingkungan . 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

    • Arah permintaan: NuGet -> plugin
    • Permintaan tidak akan berisi payload
    • Tidak ada respons yang diharapkan. Respons yang tepat adalah agar proses plugin segera keluar.

  2. Salin file dalam paket

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
      • jalur direktori tujuan
      • enumerable file dalam paket yang akan disalin ke jalur direktori tujuan
    • 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)

    • Arah permintaan: NuGet -> plugin
    • 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

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

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • enumerable jalur file dalam paket jika operasi berhasil

  6. Mendapatkan klaim operasi

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • layanan index.json untuk sumber paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • jumlah operasi yang didukung (misalnya: unduhan paket) jika operasi berhasil. Jika plugin tidak mendukung sumber paket, plugin harus mengembalikan serangkaian operasi yang didukung yang kosong.

Catatan

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

  1. Dapatkan hash paket

    • Arah permintaan: NuGet -> plugin
    • 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. Mendapatkan versi paket

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • ID paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • enumerable versi paket jika operasi berhasil

  3. Mendapatkan indeks layanan

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

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • versi alat klien NuGet
      • bahasa efektif alat klien NuGet. Ini mempertimbangkan pengaturan ForceEnglishOutput, jika digunakan.
      • batas waktu permintaan default, yang menggantikan default protokol.
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi. Kegagalan akan mengakibatkan penghentian plugin.

  6. Log

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

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • ID proses NuGet
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi.

  8. Paket prefetch

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • ID paket dan versi
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

  9. Mengatur kredensial

    • Arah permintaan: NuGet -> plugin
    • 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

    • Arah permintaan: NuGet -> plugin
    • Permintaan akan berisi:
      • tingkat log default
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi

Pesan Protokol Versi 2.0.0

  1. Dapatkan Klaim Operasi

  • Arah permintaan: NuGet -> plugin

    • Permintaan akan berisi:
      • layanan index.json untuk sumber paket
      • lokasi repositori sumber paket
    • Respons akan berisi:
      • kode respons yang menunjukkan hasil operasi
      • enumerable dari 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
  • Arah permintaan: NuGet -> plugin
  • Permintaan akan berisi:
    • Uri
    • isRetry
    • NonInteraktif
    • CanShowDialog
  • Respons akan berisi
    • Nama Pengguna
    • Kata sandi
    • Pesan
    • Daftar Jenis Autentikasi
    • MessageResponseCode