Cara menulis file Konfigurasi WinGet

Artikel
09/28/2023

Untuk membuat file Konfigurasi WinGet:

Buat file YAML setelah konvensi penamaan file Konfigurasi WinGet.
Biasakan diri Anda dengan format file Konfigurasi WinGet dan tautkan skema file saat ini.
Tentukan daftar Pernyataan (prasyarat yang diperlukan) dan Sumber Daya (daftar penginstalan dan konfigurasi pengaturan yang diperlukan untuk mendapatkan lingkungan pengembangan komputer ke status yang diinginkan) untuk disertakan dalam file.
Identifikasi modul PowerShell dan Sumber Daya Konfigurasi Status yang Diinginkan (DSC) yang diperlukan untuk menyelesaikan tugas konfigurasi yang Anda inginkan.
Tentukan arahan dan pengaturan yang diperlukan untuk setiap sumber daya konfigurasi.
Tentukan dependensi untuk setiap sumber daya.

Pelajari selengkapnya tentang menggunakan perintah konfigurasi WinGet.

Format file

Pengelola Paket Windows menggunakan manifes (file YAML) untuk menemukan dan menginstal paket untuk pengguna Windows. File Konfigurasi WinGet menggunakan format gaya YAML yang sama, menambahkan spesifikasi skema JSON untuk membantu menentukan struktur dan validasi file. Untuk lebih membantu mendeteksi apakah format file Konfigurasi WinGet Anda valid, sebaiknya gunakan Visual Studio Code dengan ekstensi YAML oleh RedHat untuk mendukung sintaks yang tepat, membantu mendeteksi kesalahan pemformatan apa pun, menyediakan dukungan hover dan penyelesaian otomatis (saat ditautkan ke file skema JSON), dan memastikan pemformatan yang valid.

Konvensi penamaan file

Konvensi untuk penamaan file Konfigurasi WinGet adalah configuration.dsc.yaml. Untuk proyek berbasis Git, konfigurasi default harus disimpan dalam direktori "konfigurasi" di: ./configurations/configuration.dsc.yaml.

Bagian dari file Konfigurasi WinGet

File Konfigurasi WinGet dipisahkan menjadi dua bagian utama:

Pernyataan: Prasyarat yang diperlukan untuk menjalankan konfigurasi.
Sumber Daya: Daftar perangkat lunak dan alat yang akan diinstal, pengaturan konfigurasi untuk penginstalan tersebut, dan pengaturan konfigurasi untuk sistem operasi Windows.

Bagian Pernyataan

Daftar pernyataan mencakup prasyarat (atau prasyarat) yang diperlukan untuk sumber daya yang tercantum dalam file Konfigurasi WinGet ini agar berhasil pada komputer yang menjalankan file. Pernyataan dapat diselesaikan secara paralel dan tidak memerlukan urutan berurutan.

Contoh pernyataan:

Versi OS: Versi minimum sistem operasi* yang diinstal pada komputer. Karena fitur ditambahkan dari waktu ke waktu ke OS, beberapa didukung untuk mendukung versi sebelumnya dan beberapa tidak. Selalu berguna untuk memeriksa versi OS minimum untuk menentukan apakah alat atau fitur tertentu mungkin didukung yang diperlukan untuk konfigurasi. Misalnya, WinGet (Pengelola Paket Windows) memerlukan minimal Windows 10, versi 1809 atau yang lebih baru. Versi Windows yang lebih lama tidak mendukung WinGet. *Dimungkinkan bagi Sumber Daya DSC PowerShell untuk mengubah status sistem, tetapi tidak akan sesuai untuk memanggil Windows Update dan memodifikasi versi OS dalam konfigurasi proyek untuk proyek sumber terbuka.

Jika pernyataan mengembalikan "false" untuk menunjukkan sistem tidak dalam keadaan yang diinginkan, Sumber Daya apa pun yang mengidentifikasi pernyataan tersebut sebagai dependensi menggunakan dependsOn bidang akan dilewati dan gagal dijalankan. Dalam hal ini, meskipun tidak ada perubahan konfigurasi yang diterapkan pada lingkungan Windows, konfigurasi ini akan dianggap sebagai hasil yang berhasil.

Bagian sumber daya

Daftar Sumber Daya mencakup semua perangkat lunak, alat, paket, dll. yang perlu diinstal dan pengaturan konfigurasi untuk sistem operasi Windows Anda atau aplikasi yang diinstal. Setiap sumber daya harus diberi nama, deskripsi arahan yang akan dilakukan dan modul PowerShell yang akan bertanggung jawab untuk melakukan arahan itu, serta pengaturan atau dependensi terkait.

Contoh file Konfigurasi WinGet

Berikut ini adalah contoh file berformat Konfigurasi configuration.dsc.yaml WinGet:

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

Komponen file ini terdiri dari:

Skema: Baris pertama dalam file konfigurasi Anda harus berisi komentar berikut: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> untuk membuat skema DSC yang diikuti oleh file. Untuk menemukan versi terbaru dari skema Konfigurasi WinGet, buka https://aka.ms/configuration-dsc-schema/. Nomor skema terbaru pada saat contoh ini adalah 0.2, sehingga skema dimasukkan sebagai: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.
Properti: Simpul akar untuk file konfigurasi adalah properties yang harus berisi versi konfigurasi (configurationVersion: 0.2.0 dalam contoh ini). Versi ini harus diperbarui sesuai dengan pembaruan pada file konfigurasi. Node properti harus berisi node assertions dan node resources .
Pernyataan: Cantumkan prasyarat (atau prasyarat) yang diperlukan untuk konfigurasi ini di bagian ini.
Sumber Daya: Bagian assertions daftar dan resources terdiri dari simpul individual resource untuk mewakili tugas penyiapan. resource harus diberi nama modul PowerShell diikuti dengan nama sumber daya DSC modul yang akan dipanggil untuk menerapkan status yang Anda inginkan: {ModuleName}/{DscResource}. Setiap sumber daya harus menyertakan directives dan settings. Secara opsional, itu juga dapat menyertakan id nilai. Saat menerapkan konfigurasi, WinGet akan tahu untuk menginstal modul dari Galeri PowerShell dan memanggil sumber daya DSC yang ditentukan.
Arahan: Bagian ini directives menyediakan informasi tentang modul dan sumber daya. Bagian ini harus menyertakan description nilai untuk menjelaskan tugas konfigurasi yang dicapai oleh modul. Nilai memungkinkan allowPrerelease Anda memilih apakah konfigurasi akan diizinkan (true) untuk menggunakan modul "Prarilis" atau tidak dari Galeri PowerShell.
Pengaturan: Nilai settings sumber daya mewakili kumpulan pasangan nilai nama yang diteruskan ke Sumber Daya PowerShell DSC. Pengaturan dapat mewakili apa pun dari apakah Mode Pengembang diaktifkan, untuk menerapkan kunci reg, atau untuk membuat pengaturan jaringan tertentu.
Dependensi: Nilai dependsOn sumber daya menentukan apakah pernyataan atau sumber daya lain harus selesai sebelum memulai tugas ini. Jika dependensi gagal, sumber daya ini juga akan gagal secara otomatis.
ID: Pengidentifikasi unik untuk instans sumber daya tertentu. Nilai id dapat digunakan jika sumber daya lain memiliki dependensi pada sumber daya ini yang diterapkan terlebih dahulu.

Mengatur bagian Sumber Daya

Ada beberapa pendekatan yang perlu dipertimbangkan saat menentukan cara mengatur bagian Sumber Daya dari file Konfigurasi WinGet Anda. Anda dapat mengatur daftar file Anda dengan:

Urutan eksekusi: Mengatur daftar sumber daya Anda sesuai dengan urutan logis di mana mereka harus dijalankan. Pendekatan ini dapat membantu pengguna untuk memahami dan mengikuti langkah-langkah otomatisasi yang dilakukan setelah file dijalankan - apa yang diinstal pertama, kedua, pengaturan apa yang diperbarui ketiga, dll.
Kemungkinan kegagalan: Mengatur daftar sumber daya Anda sesuai dengan kemungkinan potensi kegagalan dapat membantu pengguna untuk menangkap masalah sejak awal dalam proses konfigurasi dan membantu mereka memahami mengapa langkah-langkah yang tersisa mungkin gagal, memungkinkan mereka mengidentifikasi dan membuat perubahan yang diperlukan sebelum banyak waktu diinvestasikan.
Mengelompokkan jenis sumber daya serupa: Mengatur daftar sumber daya Anda dengan mengelompokkan jenis sumber daya serupa adalah pendekatan umum dalam metodologi rekayasa perangkat lunak dan mungkin yang paling akrab bagi Anda atau pengembang lain yang menggunakan file konfigurasi Anda.

Sebaiknya sertakan file README.md dengan file Konfigurasi WinGet sumber terbuka yang diterbitkan yang menyertakan pendekatan organisasi struktur file.

Menggunakan variabel ${WinGetConfigRoot}

Sumber daya DSC tertentu dapat mengambil parameter yang menentukan jalur file. Alih-alih menentukan jalur lengkap, Anda dapat menggunakan variabel ${WinGetConfigRoot} untuk menentukan direktori kerja tempat winget configure perintah dijalankan dan menambahkan jalur relatif untuk menunjuk ke file tersebut. Ini berguna untuk menggeneralisasi file konfigurasi sehingga merupakan agnostik mesin. Sumber Microsoft.VisualStudio.DSC/VSComponents daya dalam contoh di atas menampilkan fungsionalitas ini dengan menggunakan ${WinGetConfigRoot} untuk menunjuk ke file .vsconfig dalam direktori akar proyek. Ini juga berarti bahwa pengguna harus memastikan bahwa file target ada di jalur relatif berdasarkan direktori kerja saat ini sebelum menjalankan winget configure perintah.

Tempat menemukan modul Sumber Daya PowerShell DSC

Lihat daftar Sumber Daya Konfigurasi Status yang Diinginkan PowerShell yang didukung oleh Microsoft, termasuk:

Lingkungan: Mengelola variabel lingkungan untuk mesin atau proses.
MsiPackage: Menginstal atau menghapus instalan paket MSI.
Registri: Mengelola kunci atau nilai registri.
Skrip: Jalankan blok skrip PowerShell.
Layanan: Mengelola layanan Windows.
WindowsFeature: Menginstal atau menghapus instalan peran atau fitur Windows.
WindowsProcess: Memulai atau menghentikan proses Windows.

Anda juga dapat menemukan modul Sumber Daya PowerShell DSC di Galeri PowerShell. Galeri ini menghosting ratusan Modul PowerShell yang berisi sumber daya Desired State Configuration (DSC) yang dikirimkan oleh komunitas pengguna. Anda dapat memfilter hasil pencarian dengan menerapkan filter "Sumber Daya DSC" di bawah "Kategori". Repositori ini tidak diverifikasi oleh Microsoft dan berisi sumber daya dari berbagai penulis dan penerbit. Modul PowerShell harus selalu ditinjau untuk keamanan dan kredibilitas sebelum digunakan sebagai skrip arbitrer apa pun dapat disertakan. Lihat Cara memeriksa kepercayaan file Konfigurasi WinGet untuk tips selengkapnya tentang membuat file Konfigurasi WinGet yang dapat dipercaya.

Bagikan melalui