Aracılığıyla paylaş

Taşınabilir Modüller

  • Makale

Windows PowerShell .NET Framework için yazılırken, PowerShell Core .NET Coreiçin yazılır. Taşınabilir modüller, hem Windows PowerShell hem de PowerShell Core'da çalışan modüllerdir. .NET Framework ve .NET Core yüksek oranda uyumlu olsa da, ikisi arasındaki kullanılabilir API'lerde farklılıklar vardır. Windows PowerShell ve PowerShell Core'da kullanılabilen API'lerde de farklılıklar vardır. Her iki ortamda da kullanılması amaçlanan modüllerin bu farklılıkların farkında olması gerekir.

Mevcut modülü taşıma

PSSnapIn Uyarlaması

PowerShell SnapIns PowerShell Core'da desteklenmez. Ancak PSSnapIn'i PowerShell modülüne dönüştürmek basit bir işlemdir. Genellikle, PSSnapIn'dan türetilen bir sınıfın kaynak dosyasındaki PSSnapIn kaydının kodu tek bir dosyada bulunur. Bu kaynak dosyayı derlemeden kaldırın; artık gerekli değil.

New-ModuleManifest kullanarak PSSnapIn kayıt kodu gereksiniminin yerini alan yeni bir modül bildirimi oluşturun. PSSnapIn bazı değerler (Açıklamagibi) modül manifestosunda yeniden kullanılabilir.

Modül bildirimindeki RootModule özelliği, cmdlet'leri uygulayan derlemenin (.dll) adına ayarlanmalıdır.

.NET Taşınabilirlik Çözümleyicisi (diğer bir deyişle APIPort)

Windows PowerShell için yazılmış modülleri PowerShell Core ile çalışacak şekilde bağlantı noktasına getirmek için .NET Taşınabilirlik Çözümleyicisiile başlayın. Modülde kullanılan .NET API'lerinin .NET Framework, .NET Core ve diğer .NET çalışma zamanlarıyla uyumlu olup olmadığını belirlemek için bu aracı derlenmiş derlemenizde çalıştırın. Araç, varsa alternatif API'ler önerir. Aksi takdirde, çalışma zamanı denetimleri eklemeniz ve belirli çalışma zamanlarında kullanılamayan özellikleri kısıtlamanız gerekebilir.

Yeni modül oluşturma

Yeni bir modül oluşturuyorsanız, .NET CLIkullanmanız gerekir.

PowerShell Standart modül şablonunu yükleme

.NET CLI yüklendikten sonra, basit bir PowerShell modülü oluşturmak için bir şablon kitaplığı yükleyin. Modül Windows PowerShell, PowerShell Core, Windows, Linux ve macOS ile uyumlu olacaktır.

Aşağıdaki örnekte şablonun nasıl yükleneceği gösterilmektedir:

dotnet new install Microsoft.PowerShell.Standard.Module.Template

The following template packages will be installed:
   Microsoft.PowerShell.Standard.Module.Template

Success: Microsoft.PowerShell.Standard.Module.Template::0.1.3 installed the following templates:
Template Name               Short Name  Language  Tags
--------------------------  ----------  --------  -------------------------
PowerShell Standard Module  psmodule    [C#]      Library/PowerShell/Module

Yeni modül projesi oluşturma

Şablon yüklendikten sonra, bu şablonu kullanarak yeni bir PowerShell modülü projesi oluşturabilirsiniz. Bu örnekte örnek modüle 'myModule' adı verilir.

PS> mkdir myModule

    Directory: C:\Users\Steve

Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 8/3/2018 2:41 PM myModule

PS> cd myModule
PS C:\Users\Steve\myModule> dotnet new psmodule
The template "PowerShell Standard Module" was created successfully.

Processing post-creation actions...
Restoring  C:\Users\Steve\myModule\myModule.csproj:
  Determining projects to restore...
  Restored C:\Users\Steve\myModule\myModule.csproj (in 184 ms).
Restore succeeded.

Modülü oluşturma

Projeyi derlemek için standart .NET CLI komutlarını kullanın.

dotnet build

PS C:\Users\Steve\myModule> dotnet build
MSBuild version 17.6.3+07e294721 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  PowerShellPG -> C:\Users\Steve\myModule\bin\Debug\netstandard2.0\myModule.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.36

Modülü test etme

Modülü derledikten sonra içeri aktarabilir ve örnek cmdlet'ini yürütebilirsiniz.

Import-Module .\bin\Debug\netstandard2.0\myModule.dll
Test-SampleCmdlet -?
Test-SampleCmdlet -FavoriteNumber 7 -FavoritePet Cat

NAME
    Test-SampleCmdlet

SYNTAX
    Test-SampleCmdlet [-FavoriteNumber] <int> [[-FavoritePet] {Cat | Dog | Horse}] [<CommonParameters>]


ALIASES
    None


REMARKS
    None


FavoriteNumber FavoritePet
-------------- -----------
             7 Cat

Modülde hata ayıklama

Modülde hata ayıklamak için Visual Studio Code ayarlama kılavuzu için bkz. Derlenmiş cmdlet'lerde hata ayıklamak için Visual Studio Code kullanma.

Destekleyici teknolojiler

Aşağıdaki bölümlerde, bu şablon tarafından kullanılan bazı teknolojiler ayrıntılı olarak açıklanmaktadır.

.NET Standart Kitaplığı

.NET Standard , tüm .NET uygulamalarında kullanılabilen .NET API'lerinin resmi bir belirtimidir. .NET Standard'ı hedefleyen yönetilen kod, .NET Standard'ın bu sürümüyle uyumlu .NET Framework ve .NET Core sürümleriyle çalışır.

Not

.NET Standard'da bir API mevcut olsa da, .NET Core'daki API uygulaması çalışma zamanında bir PlatformNotSupportedException oluşturabilir, bu nedenle Windows PowerShell ve PowerShell Core ile uyumluluğu doğrulamak için en iyi yöntem modülünüzün testlerini her iki ortamda da çalıştırmaktır. Ayrıca modülünüzün platformlar arası olması amaçlanıyorsa Linux ve macOS üzerinde testler çalıştırın.

.NET Standard'ın hedeflenmesi, modül geliştikçe uyumsuz API'lerin modülde yanlışlıkla kullanılmamasını sağlamaya yardımcı olur. Uyumsuzluklar çalışma zamanı yerine derleme zamanında bulunur.

Ancak uyumlu API'ler kullandığınız sürece bir modülün hem Windows PowerShell hem de PowerShell Core ile çalışması için .NET Standard'ı hedeflemek gerekmez. Ara Dil (IL), iki çalışma zamanı arasında uyumludur. .NET Standard 2.0 ile uyumlu .NET Framework 4.6.1'i hedefleyebilirsiniz. API'leri .NET Standard 2.0 dışında kullanmıyorsanız modülünüz yeniden derleme olmadan PowerShell Core 6 ile çalışır.

PowerShell Standart Kitaplığı

PowerShell Standart kitaplığı, bu standardın sürümünden büyük veya buna eşit tüm PowerShell sürümlerinde kullanılabilen resmi bir PowerShell API belirtimidir.

Örneğin PowerShell Standard 5.1 hem Windows PowerShell 5.1 hem de PowerShell Core 6.0 veya üzeri sürümlerle uyumludur.

Modülünüzü PowerShell Standart Kitaplığı kullanarak derlemenizi öneririz. Kitaplık, API'lerin hem Windows PowerShell hem de PowerShell Core 6'da kullanılabilir ve uygulanmasını sağlar. PowerShell Standard her zaman ileriye dönük uyumlu olması amaçlanmıştır. PowerShell Standart Kitaplığı 5.1 kullanılarak oluşturulan bir modül her zaman PowerShell'in gelecekteki sürümleriyle uyumlu olacaktır.

Modül Manifestosu

Windows PowerShell ve PowerShell Core ile Uyumluluğu Gösteren

Modülünüzün hem Windows PowerShell hem de PowerShell Core ile çalıştığını doğruladıktan sonra, modül bildiriminin CompatiblePSEditions özelliğini kullanarak uyumluluğu açıkça belirtmesi gerekir. Desktop değeri modülün Windows PowerShell ile uyumlu olduğu, Core değeri ise modülün PowerShell Core ile uyumlu olduğu anlamına gelir. Hem Desktop hem de Core dahil olmak, modülün hem Windows PowerShell hem de PowerShell Core ile uyumlu olduğu anlamına gelir.

Dikkat

Core otomatik olarak modülün Windows, Linux ve macOS ile uyumlu olduğu anlamına gelmez. CompatiblePSEditions özelliği PowerShell v5'te kullanıma sunulmuştur. CompatiblePSEditions özelliğini kullanan modül bildirimleri PowerShell v5'in önceki sürümlerinde yüklenemiyor.

İşletim Sistemi Uyumluluğunu Gösterir

İlk olarak modülünüzün Linux ve macOS üzerinde çalıştığını doğrulayın. Ardından modül bildiriminde bu işletim sistemleriyle uyumluluğu belirtin. Bu, kullanıcıların PowerShell Galerisiyayımlandığında işletim sistemlerine yönelik modülünüzü bulmalarını kolaylaştırır.

Modül bildiriminde PrivateData özelliğinin PSData bir alt özelliği vardır. PSData'in isteğe bağlı Tags özelliği, PowerShell Galerisi'nde görünen değerlerin bir dizisini alır. PowerShell Galerisi aşağıdaki uyumluluk değerlerini destekler:

Etiket Açıklama
PSEdition_Core PowerShell Core 6 ile uyumlu
PSEdition_Desktop Windows PowerShell ile uyumlu
Windows Windows ile uyumlu
Linux Linux ile uyumlu (belirli bir dağıtım yok)
macOS macOS ile uyumlu

Örnek:

@{
    GUID = "4ae9fd46-338a-459c-8186-07f910774cb8"
    Author = "Microsoft Corporation"
    CompanyName = "Microsoft Corporation"
    Copyright = "(C) Microsoft Corporation. All rights reserved."
    HelpInfoUri = "https://go.microsoft.com/fwlink/?linkid=855962"
    ModuleVersion = "1.2.4"
    PowerShellVersion = "3.0"
    ClrVersion = "4.0"
    RootModule = "PackageManagement.psm1"
    Description = 'PackageManagement (a.k.a. OneGet) is a new way to discover and install software packages from around the web.
 it's a manager or multiplexer of existing package managers (also called package providers) that unifies Windows package management with a single Windows PowerShell interface. With PackageManagement, you can do the following.
  - Manage a list of software repositories in which packages can be searched, acquired and installed
  - Discover software packages
  - Seamlessly install, uninstall, and inventory packages from one or more software repositories'

    CmdletsToExport = @(
        'Find-Package',
        'Get-Package',
        'Get-PackageProvider',
        'Get-PackageSource',
        'Install-Package',
        'Import-PackageProvider'
        'Find-PackageProvider'
        'Install-PackageProvider'
        'Register-PackageSource',
        'Set-PackageSource',
        'Unregister-PackageSource',
        'Uninstall-Package'
        'Save-Package'
    )

    FormatsToProcess  = @('PackageManagement.format.ps1xml')

    PrivateData = @{
        PSData = @{
            Tags = @('PackageManagement', 'PSEdition_Core', 'PSEdition_Desktop', 'Windows', 'Linux', 'macOS')
            ProjectUri = 'https://oneget.org'
        }
    }
}

Yerel Kitaplıklara Bağımlılık

Farklı işletim sistemlerinde veya işlemci mimarilerinde kullanılmak üzere tasarlanan modüller, bazı yerel kitaplıklara bağımlı olan yönetilen bir kitaplığa bağlı olabilir.

PowerShell 7'den önce, yönetilen kitaplığın doğru şekilde bulabilmesi için uygun yerel dll'yi yüklemek amacıyla özel bir kod yazmak gerekirdi.

PowerShell 7 ile yüklenecek yerel ikili dosyalar, .NET RID Kataloğu gösteriminin bir alt kümesinden sonra yönetilen kitaplığın konumundaki alt klasörlerde aranır.

managed.dll folder
    |
    |--- 'win-x64' folder
    |       |--- native.dll
    |
    |--- 'win-x86' folder
    |       |--- native.dll
    |
    |--- 'win-arm' folder
    |       |--- native.dll
    |
    |--- 'win-arm64' folder
    |       |--- native.dll
    |
    |--- 'linux-x64' folder
    |       |--- native.so
    |
    |--- 'linux-x86' folder
    |       |--- native.so
    |
    |--- 'linux-arm' folder
    |       |--- native.so
    |
    |--- 'linux-arm64' folder
    |       |--- native.so
    |
    |--- 'osx-x64' folder
    |       |--- native.dylib