PackageProvider Interface

Overview (c#)

To create your own provider, download the sdk https://github.com/OneGet/ProviderSdk, add your business logic and test it. Once you are ready for others to consume your provider, you may follow the guidance https://github.com/OneGet/oneget/wiki/How-to-submit-your-provider to submit it. You may also try out a sample C# based provider: https://github.com/OneGet/NuGetProvider.

A PackageManagement PackageProvider that is implemented in C# must expose functions with signatures that match the following:

string PackageProviderName;

void InitializeProvider(Request request);
void GetFeatures(Request request);
void GetDynamicOptions(string category, Request request);

void AddPackageSource(string name, string location, bool trusted, Request request);
void RemovePackageSource(string name, Request request);
void ResolvePackageSources(Request request);

void FindPackage(string name, string requiredVersion, string minimumVersion, string maximumVersion, int id, Request r)
void FindPackageByFile(string file, int id, Request request);
void FindPackageByUri(Uri uri, int id, IRequest requestObject);
void DownloadPackage(string fastPackageReference, string destLocation, Request request)
void GetInstalledPackages(string name, string requiredVersion, string minimumVersion, string maximumVersion, Request r)
void InstallPackage(string fastPackageReference, Request request)
void UninstallPackage(string fastPackageReference, Request request)

Overview (PowerShell)

For the PowerShell based package provider, you may try out a sample PowerShell based provider: https://github.com/OneGet/MyAlbum-Sample-Provider. A PackageManagement PackageProvider that is implemented in PowerShell must be written as a module that exposes functions with signatures that match the following:

function Get-PackageProviderName
function Initialize-Provider
function Get-Feature
function Get-DynamicOptions
function Add-PackageSource
function Remove-PackageSource
function Resolve-PackageSource
function Find-Package
function Find-PackageByFile 
function Find-PackageByUri
function Download-Package
function Get-InstalledPackage
function Install-Package
function UnInstall-Package

Required Methods

Method: `PackageProviderName`

Description

Returns the name of this PackageProvider

Necessity

This is required. Without this, the PackageProvider implementation will not be recognized, and will not load.

Syntax

string PackageProviderName { }

function Get-PackageProviderName { }

Return Value

As string representing the name for this package provider. This value is exposed to the user.

Exceptions

If the PackageProvider has a failure, it should throw an exception. However if an exception or Write-Error from this function, the provider will not be loaded.

Remarks

Due to security reasons, PackageManagement requires provider binary to contain a provider.manifest. For more information on how to build a provider with provider.manifest injected, see the .csproj project files on https://github.com/OneGet/ProviderSdk.

Optional Methods

Method: `InitializeProvider`

Description

Allows the provider to do one-time initialization.

Necessity

If the PackageProvider requires one-time initialization at provider load-time, this function is required.

Syntax

void InitializeProvider(Request request);

function Initialize-Provider{ 
  param(
  )
}

Parameters

None.

Additional Options

None.

Response

None.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. The PackageManagement will continue trying to load the provider.

Method: `GetFeatures`

Description

Allows the provider to define what features your provider supports.
This is primarily for others to leverage your provider. Here is the existing features defined by PackageManagement:

    SupportsPowerShellModules = "supports-powershell-modules";    === find, install, powershell modules
    SupportsRegexSearch       = "supports-regex-search";          === support Regualar expression search
    SupportsWildcardSearch    = "supports-wildcard-search";       === support wildcard search

    SupportedExtensions       = "file-extensions";                === package file extensions, e.g., .msi, .nupkg
    SupportedSchemes          = "uri-schemes";                    === url shemes, e.g., http, https, file
    MagicSignatures           = "magic-signatures";               === bytes at the begining of a package file, .cab, .zip

Necessity

If the PackageProvider requires to define a feature, this function is required.

Syntax

void GetFeatures(Request request)

function Get-Feature{ 
  param(
  )
}

Parameters

None.

Additional Options

None.

Response

In C#, call request.Yield () with a dictionary regarding the features you are defining. In PowerShell, call Write-Output. For example

       Write-out -InputObject (New-Feature -name "file-extensions" -values @(".png"))

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, call request.WriteError() or Write-Error for PowerShell. The ongoing operation will continue and warning message will be displayed in the PowerShell console.

Method: `GetDynamicOptions`

Description

Gets the dynamic options for a specified operation

Necessity

If the PackageProvider wishes to allow the user to specify additional options, this function must be implemented.

Syntax

void GetDynamicOptions(OptionCategory category, Request request);

function Get-Options{ 
  param(
        [Microsoft.PackageManagement.MetaProvider.PowerShell.OptionCategory] 
        $category      
    )
}

Parameters

Parameter	Type	Description
`category`	`OptionCategory`	the category of options that the host is requesting (See [[OptionCategory enum

Additional Options

None.

Response

For each installed package found, the PackageProvider must call request.YieldDynamicOption( ) with the details of the dynamic option.

Powershell-specific
Instead of calling $request.YieldDynamicOption( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.DynamicOption object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, call request.WriteError() or Write-Error for PowerShell. The ongoing operation will continue but there are no dynamic options for the category, and error message will be displayed in the PowerShell console.

Method: `AddPackageSource`

Description:

Adds a (or replaces an existing) package source.

Package Sources are always managed by the PackageProvider.

Necessity

This function is required if the PackageProvider supports user-specified package sources

Syntax

void AddPackageSource(string name, string location, bool trusted, Request request);

function Add-PackageSource
{
    [CmdletBinding()]
    param
    (
        [string]
        $Name,
        [string]
        $Location,
        [bool]
        $Trusted
    ) 
}

Parameters

Parameter	Type	Description
`name`	`string`	the name the user is giving to the package source
`location`	`string`	the location that the source points to. (Uri, Filepath, or any other destination format supported by the package provider)
`trusted`	`bool`	Indicates whether the user trusts packages from this source

Response

If a package source is added or updated, the PackageProvider must call request.YieldPackageSource( ) with the details regarding the package source

Powershell-specific
Instead of calling $request.YieldPackageSource( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.PackageSource object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider is unable to fulfill add the source, it should throw an exception.

Method: `RemovePackageSource`

Description:

Removes an existing package source.

Package Sources are always managed by the PackageProvider.

Necessity

This function is required if the PackageProvider supports user-specified package sources

Syntax

void RemovePackageSource(string name, Request request)

function Remove-PackageSource { 
  param(
    [string] $name,      
    )
}

Parameters

Parameter	Type	Description
`name`	`string`	the name of the package source the user wants to remove

Response

If a package source is removed the PackageProvider must call request.YieldPackageSource( ) with the details regarding the package source that was removed.

Powershell-specific
Instead of calling $request.YieldPackageSource( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.PackageSource object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider is unable to remove the source, it should throw an exception. If the PackageProvider is does not have a source with that name, no exception should be thrown.

Method: `ResolvePackageSources`

Description

Resolves the registered package sources that this provider is aware of.

Necessity

If the PackageProvider supports user-specified package sources, this function should be implemented.

Syntax

void ResolvePackageSources(Request request)

function Resolve-PackageSource { 
  param(     
    )
}

Parameters

None.

Additional Options

None.

Response

For each package source that the provider can handle, the PackageProvider must call request.YieldPackageSource( ).

Powershell-specific
Instead of calling $request.YieldPackageSource( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.PackageSource object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. If there are no registered package sources for this proivder, this must not throw an exception.

Method: `FindPackage`

Description

Finds packages given name

Necessity

If the PackageProvider supports searching for packages given a name, this method is required.

Syntax

void FindPackage(string name, string requiredVersion, string minimumVersion, string maximumVersion, int id, Request req);

function Find-Package { 
  param(
    [string] $name,      
    [string] $requiredVersion,  
    [string] $minimumVersion,     
    [string] $maximumVersion
    )
}

# Alternative, accepts multiple names as first parameter
function Find-Package { 
  param(
    [string[]] $names,      
    [string] $requiredVersion,  
    [string] $minimumVersion,     
    [string] $maximumVersion
    )
}

Parameters

Parameter	Type	Description
`name`	`string`	a singular string name to search for a package. Any wildcards must be handled by the `PackageProvider`
`names` (PowerShell only)	`string[]`	an array of strings name to search for a package. Any wildcards must be handled by the `PackageProvider`
`requiredVersion`	`string`	the exact version the user is requesting. if this is null or empty, the user has not specified a specific version
`minimumVersion`	`string`	the minimum version the user is requesting. if this is null or empty, the user has not specified a minimum version
`maximumVersion`	`string`	the maximum version the user is requesting. if this is null or empty, the user has not specified a maximum version
`id`	`int`	reserved

Additional Options

Additional options about the request can be retrieved from the Request object.

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request. Request.PackageSources returns the collection of the package sources the user requested, or an empty collection if the user did not specify package sources.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package found, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. Finding 0 results must not throw an exception.

Method: `FindPackageByFile`

Description

Finds packages given a path to a specific file

Necessity

If the PackageProvider supports searching for packages given a file, this method is required.

Syntax

void FindPackageByFile(string file, int id, Request request)

function Find-PackageByFile { 
  param(
    [string] $filePath,      
    )
}

# Alternative, accepts multiple names as first parameter
function Find-PackageByFile { 
  param(
    [string[]] $filePaths,      
    )
}

Parameters

Parameter	Type	Description
`filePath`	`string`	a singular string file path to resolve to a package.
`filePaths` (PowerShell only)	`string[]`	an array of strings for file paths to resolve to a package.
`id`	`int`	reserved

Additional Options

Additional options about the request can be retrieved from the Request object.

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package found, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. Finding 0 results must not throw an exception.

Method: `FindPackageByUri`

Description

Finds packages given a URI

Necessity

If the PackageProvider supports searching for packages given an URI, this method is required.

Syntax

void FindPackageByUri(Uri location, Request request);

function Find-PackageByUri { 
  param(
    [Uri] $location,      
    )
}

# Alternative, accepts multiple names as first parameter
function Find-PackageByUri { 
  param(
    [Uri[]] $locations,      
    )
}

Parameters

Parameter	Type	Description
`location`	`Uri`	a URI to an expected package location.
`locations` (PowerShell only)	`Uri[]`	an array of URIs to expected package locations.

Additional Options

Additional options about the request can be retrieved from the Request object.

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package found, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. Finding 0 results must not throw an exception.

Method: `DownloadPackage`

Description

Download a package

Necessity

If the PackageProvider can save packages, this function must be implemented.

Syntax

void DownloadPackage(string fastPackageReference, string destLocation, Request request)

function Download-Package
{ 
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]
        $FastPackageReference,
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Location
    )

Parameters

Parameter	Type	Description
`fastPackageReference`	`string`	a string (originally obtained from this `PackageProvider` via a call to one of the `FindPackage` methods) that the Provider can use to uniquely reconstitute the specific package information. (i.e., the data required to quickly* find a specific package again, serialized to a string)

Additional Options

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package saved, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception.

Method: `GetInstalledPackages`

Description

Gets the installed packages

Necessity

If the PackageProvider can detect if a package is installed, it should implement this function.

Syntax

void GetInstalledPackages(string name, string requiredVersion, string minimumVersion, string maximumVersion, Request req);

function Get-InstalledPackage
{ 
    [CmdletBinding()]
    param
    (
        [Parameter()]
        [string]
        $Name,
        [Parameter()]
        [Version]
        $RequiredVersion,
        [Parameter()]
        [Version]
        $MinimumVersion,
        [Parameter()]
        [Version]
        $MaximumVersion
    )

Parameters

Parameter	Type	Description
`name`	`string`	a name of a package to match. if this is null or empty, the user did not specify a package to match.
`requiredVersion`	`string`	the exact version the user is requesting. if this is null or empty, the user has not specified a specific version
`minimumVersion`	`string`	the minimum version the user is requesting. if this is null or empty, the user has not specified a minimum version
`maximumVersion`	`string`	the maximum version the user is requesting. if this is null or empty, the user has not specified a maximum version

Additional Options

Additional options about the request can be retrieved from the Request object.

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each installed package found, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception. Finding 0 results must not throw an exception.

Method: `InstallPackage`

Description

Installs a package

Necessity

If the PackageProvider can install packages, this function must be implemented.

Syntax

void InstallPackage(string fastPackageReference, Request request);

function Install-Package{ 
  param(
	[string] fastPackageReference
  )
}

Parameters

Parameter	Type	Description
`fastPackageReference`	`string`	a string (originally obtained from this `PackageProvider` via a call to one of the `FindPackage` methods) that the Provider can use to uniquely reconstitute the specific package information. (i.e., the data required to quickly* find a specific package again, serialized to a string)

Additional Options

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package installed, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception.

Method: `UninstallPackage`

Description

Uninstalls a package

Necessity

If the PackageProvider can install packages, this function must be implemented.

Syntax

void UninstallPackage(string fastPackageReference, Request request);

function Uninstall-Package{ 
  param(
	[string] fastPackageReference
  )
}

Parameters

Parameter	Type	Description
`fastPackageReference`	`string`	a string (originally obtained from this `PackageProvider` via a call to the `GetInstalledPackage` method) that the Provider can use to uniquely reconstitute the specific package information. (i.e., the data required to quickly find a specific package again, serialized to a string)

Additional Options

Dynamic options Request.Options returns a Hashtable of the all the dynamic options passed into the request.
Powershell Specific options $request.PSCredential returns any credential object passed in from the user. Null if not specified
.NET Specific options Request.CredentialName returns a the name of the credential object passed in from the user. Null if not specified Request.CredentialPassword returns a the password (as a SecureString) of the credential object passed in from the user. Null if not specified.

Response

For each package removed, the PackageProvider must call request.YieldPackage( ) with the details regarding the package.

Powershell-specific
Instead of calling $request.YieldPackage( ), PowerShell-based providers can simply Write-Output an instance of a Microsoft.OneGet.PowerShell.SoftwareIdentity object.

Return Value

There is no return value from this function.

Exceptions

If the PackageProvider encounters an unexpected error, it should throw an exception.
If the provider is asked to uninstall a package is not currently installed, this should not throw an exception.

PackageProvider Interface

Overview (c#)

Overview (PowerShell)

Required Methods

Method: PackageProviderName

Description

Necessity

Syntax

Return Value

Exceptions

Remarks

Optional Methods

Method: InitializeProvider

Description

Necessity

Syntax

Parameters

Additional Options

Response

Return Value

Exceptions

Method: GetFeatures

Description

Necessity

Syntax

Parameters

Additional Options

Response

Return Value

Exceptions

Method: GetDynamicOptions

Description

Necessity

Syntax

Parameters

Additional Options

Response

Return Value

Exceptions

Method: AddPackageSource

Description:

Necessity

Syntax

Parameters

Response

Return Value

Exceptions

Method: RemovePackageSource

Description:

Necessity

Syntax

Parameters

Response

Return Value

Exceptions

Method: ResolvePackageSources

Description

Necessity

Syntax

Parameters

Additional Options

Response

Return Value

Exceptions

Method: FindPackage

Description

Necessity

Syntax

Parameters

Additional Options

Response

Return Value

Exceptions

Method: FindPackageByFile

Description

Necessity

Syntax

Parameters

Additional Options

Response

Method: `PackageProviderName`

Method: `InitializeProvider`

Method: `GetFeatures`

Method: `GetDynamicOptions`

Method: `AddPackageSource`

Method: `RemovePackageSource`

Method: `ResolvePackageSources`

Method: `FindPackage`

Method: `FindPackageByFile`

Method: `FindPackageByUri`

Method: `DownloadPackage`

Method: `GetInstalledPackages`

Method: `InstallPackage`

Method: `UninstallPackage`