Aracılığıyla paylaş

Komut tabanlı DSC Kaynak bildirimi şema başvurusu

  • Makale

Özet

Komut tabanlı DSC Kaynağını tanımlayan veri dosyası.

Meta veriler

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
Type:          object

Tarif

Her komut tabanlı DSC Kaynağının bir bildirimi olmalıdır. Bildirim dosyası şu şekilde olmalıdır:

  1. PATH ortam değişkeninde bulunabilir.
  2. JSON veya YAML olarak biçimlendirilmelidir.
  3. <name>.dsc.resource.<extension>adlandırma kuralını izleyin. Geçerli uzantılar json, ymlve yamliçerir.
  4. Bu belgede açıklanan şema için geçerli olmalıdır.

Bu belgenin geri kalanında bildirimin şeması açıklanmaktadır.

Gerekli özellikler

Bildirim şu özellikleri içermelidir:

Özellikler

$schema

$schema özelliği, bildirimin doğrulanması için bu şemanın kurallı URI'sini gösterir. Bu özellik zorunludur. DSC, bildirimi doğru JSON şemasına göre doğrulamak için bu değeri kullanır.

Şemanın her sürümü için üç geçerli URL vardır:

  • .../resource/manifest.json

    Kurallı paketlenmemiş şemanın URL'si. Doğrulama için kullanıldığında, doğrulayıcı istemcinin bu şemayı ve başvurduğunda her şemayı alması gerekir.

  • .../bundled/resource/manifest.json

    Paketlenmiş şemanın URL'si. Doğrulama için kullanıldığında, doğrulayıcı istemcinin yalnızca bu şemayı alması gerekir.

    Bu şema, JSON Schema 2020-12 için tanıtılan paketleme modelini kullanır. DSC bu şemayı kullandığında belgeyi doğrulamaya devam etse de, diğer araçlar beklenmeyen şekillerde hata verebilir veya davranabilir.

  • .../bundled/resource/manifest.vscode.json

    Gelişmiş yazma şemasının URL'si. Diğer şemaların içermediği bağlamsal yardım ve kod parçacıkları sağlayan ek tanımlar içerdiğinden bu şema diğer şemalardan çok daha büyüktür.

    Bu şemada yalnızca VS Code tarafından tanınan anahtar sözcükler kullanılır. DSC bu şemayı kullandığında belgeyi doğrulamaya devam etse de, diğer araçlar beklenmeyen şekillerde hata verebilir veya davranabilir.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

tür

type özelliği, kaynağın tam tür adını temsil eder. dsc resource * komutları kullanılırken yapılandırma belgelerinde ve --resource bayrağının değeri olarak kaynağı belirtmek için kullanılır. Kaynak türü adları hakkında daha fazla bilgi için bkz. DSC Kaynağı tam tür adı şema başvurusu.

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

Sürüm

version özelliği, geçerli bir anlamsal sürüm (semver) dizesi olarak kaynağın geçerli sürümü olmalıdır. Sürüm, yönettiği yazılıma değil kaynağa uygulanır.

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

tarif

description özelliği, kaynağın amacına yönelik bir özet tanımlar. Bu özelliğin değeri kısa bir dize olmalıdır.

Type:     string
Required: false

tür

kind özelliği, DSC'nin kaynağı nasıl işlemesi gerektiğini tanımlar. DSC üç tür komut tabanlı DSC Kaynağını destekler: Resource, Groupve Adapter.

kaynak bildiriminde kind tanımlanmadığında, DSC özelliği için değeri çıkarsar. adapter özelliği kaynak bildiriminde tanımlanmışsa, DSC Adapterolarak kind değerini çıkarsar. adapter özelliği tanımlanmamışsa, DSC kind değerini Resourceolarak çıkarsar. DSC, bildirimin bir grup kaynağı için olup olmadığını çıkaramaz.

Bir grup kaynağı tanımlarken bildirimdeki kind özelliğini her zaman açıkça Groupolarak tanımlayın.

Daha fazla bilgi için bkz. DSC Kaynak türü şema başvurusu.

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

Etiketler

tags özelliği, kaynak için aranabilir terimlerin listesini tanımlar. Bu özelliğin değeri bir dize dizisi olmalıdır. Her etiket yalnızca alfasayısal karakterler ve alt çizgi içermelidir. Başka karaktere izin verilmez. Her etiket benzersiz olmalıdır.

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

Ihracat

export özelliği, her örneğin geçerli durumunu almak için kaynağın nasıl çağrılacaklarını tanımlar. Bu özellik tanımlandığında kullanıcılar şunları yapabilir:

  • Kullanılabilir bir yapılandırma belgesi oluşturmak için dsc yapılandırma dışarı aktarma komutunun giriş yapılandırmasında kaynağın bir örneğini belirtin.
  • Kaynağın her örneğini tanımlayan bir yapılandırma belgesi oluşturmak için dsc kaynak dışarı aktarma komutuyla kaynağı belirtin.
  • kaynağı dsc get komutuyla ve kaynağın her örneği için geçerli durumu döndürmek için --all seçeneğiyle belirtin.

Bu özelliğin değeri bir nesne olmalıdır. Çağıracak komutun adını tanımlayan nesnenin executable özelliği zorunludur. args özelliği isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimi dışarı aktarma özelliği şema başvurusu.

Type:     object
Required: true

Al

get özelliği, bir örneğin geçerli durumunu almak için kaynağın nasıl çağrılacaklarını tanımlar. Bu özellik tüm kaynaklar için zorunludur.

Bu özelliğin değeri bir nesne olmalıdır. Çağıracak komutun adını tanımlayan nesnenin executable özelliği zorunludur. args ve input özellikleri isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimiözellik şema başvurusu alma.

Type:     object
Required: true

ayarlamak

set özelliği, örneğin istenen durumunu ayarlamak için kaynağın nasıl çağrılyacağını tanımlar. Ayrıca bu yöntem için kaynaktan çıkışın nasıl işlendiği de tanımlıyor. Bu özellik tanımlanmadığında, DSC kaynağın örneklerini yönetemez. Yalnızca geçerli durumunu alabilir ve örneğin istenen durumda olup olmadığını test edebilir.

Bu özelliğin değeri bir nesne olmalıdır. Çağrılacak komutun adını tanımlayan executable özelliği zorunludur. args input, implementsPretestve returns özellikleri isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimi kümesi özellik şeması başvurusu.

Type:     object
Required: false

whatIf

Set komutunun bir örneği değiştirip değiştirmeyeceğini ve DSC Kaynağından çıkışın nasıl işlenip işlenmeyeceğini belirtmek için DSC'nin DSC Kaynağını nasıl çağırması gerektiğini tanımlar. Bir kaynak bildirimde bu yöntemi tanımlamazsa, DSC kaynak için test işleminin sonucunu ayarlanan sonuba dönüştürerek bu davranışı sentezler.

Bu özelliğin değeri bir nesne olmalıdır. Çağrılacak komutun adını tanımlayan executable özelliği zorunludur. args input, implementsPretestve returns özellikleri isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimi whatIf özellik şeması başvurusu.

test

test özelliği, örneğin istenen durumda olup olmadığını test etmek için kaynağın nasıl çağrıldığını tanımlar. Ayrıca bu yöntem için kaynaktan çıkışın nasıl işlendiği de tanımlıyor. Bu özellik tanımlanmadığında DSC, DSC Kaynağının örnekleri için temel bir yapay test gerçekleştirir.

Bu özelliğin değeri bir nesne olmalıdır. Çağıracak komutun adını tanımlayan nesnenin executable özelliği zorunludur. args inputve returns özellikleri isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimi test özelliği şema başvurusu.

Type:     object
Required: false

Doğrulamak

validate özelliği, örneklerini doğrulamak için DSC Grup Kaynağının nasıl çağrılacağını tanımlar. Bu özellik DSC Grup Kaynakları için zorunludur. DSC, diğer tüm kaynaklar için bu özelliği yoksayar.

Bu özelliğin değeri bir nesne olmalıdır. Çağıracak komutun adını tanımlayan nesnenin executable özelliği zorunludur. args özelliği isteğe bağlıdır. Daha fazla bilgi için bkz. DSC Kaynak bildirimi doğrulama özelliği şema başvurusu.

Type:     object
Required: false

Sağlayıcı

belirtildiğinde, provider özelliği kaynağı DSC Kaynak Sağlayıcısı olarak tanımlar.

Bu özelliğin değeri bir nesne olmalıdır. Nesnenin list ve config özellikleri zorunlu. list özelliği, sağlayıcının yönetebileceği kaynakları döndürmek için sağlayıcının nasıl çağrılabileceğini tanımlar. config özelliği, sağlayıcının girişi nasıl beklediğini tanımlar. Daha fazla bilgi içinDSC Kaynak bildirimi sağlayıcısı özellik şeması başvurusuna bakın.

exitCodes

exitCodes özelliği, kaynak ve anlamları için geçerli çıkış kodları kümesini tanımlar. Bu özelliği aşağıdaki durumlarda anahtar-değer çiftleri kümesi olarak tanımlayın:

  • Anahtar, kaynağın bilinen çıkış koduyla eşleşen imzalı bir tamsayı içeren bir dizedir. Çıkış kodu sabit işaretli bir tamsayı olmalıdır. Çıkış kodu için alternatif biçimler kullanamazsınız. Örneğin, "Erişim reddedildi" için onaltılık değer 0x80070005 yerine çıkış kodunu -2147024891olarak belirtin.
  • değeri, bir insan okuyucu için bu çıkış kodunun anlamsal anlamını açıklayan bir dizedir.

DSC, çıkış kodu 0 başarılı bir işlem ve diğer çıkış kodlarını hata olarak yorumlar.

Bahşiş

Yaml'de kaynak bildiriminizi yazarsanız, YAML dosyasının doğru ayrıştırılabilmesi için çıkış kodunu tek tırnak içinde sarmaladığınızdan emin olun. Mesela:

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

şema

schema özelliği, kaynağın bir örneğini doğrulayan JSON şemasının nasıl alındığını tanımlar. Bu özellik her zaman aşağıdaki özelliklerden birini tanımlayan bir nesne olmalıdır:

  • command - command özelliğini belirttiğinizde, DSC JSON şemasını almak için tanımlı komutu çağırır.
  • embedded - embedded özelliğini belirttiğinizde, DSC tanımlanan değeri JSON şeması olarak kullanır.

Daha fazla bilgi için bkz. DSC Kaynak bildirimi şema özelliği başvurusu.

Type:     object
Required: true