Skip to content

PackageProvider Interface

Jump to bottom Edit New page
Jianyun edited this page Feb 25, 2016 · 21 revisions

###Overview (c#)### You may try out a sample C# based provider: https://github.com/OneGet/NuGetProvider. 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.

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.

Remarks

Due to security reasons, PackageManagement requires C#-based providers 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. If an exception is thrown from this function, the provider will not be loaded.

Method: GetFeatures

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 GetFeatures(Request request)
function Get-Feature{ 
  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. If an exception is thrown from this function, the provider will not be loaded.

Method: GetDynamicOptions

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 GetDynamicOptions(string category, Request request);
function Get-DynamicOptions
{
    param
    (
        [Microsoft.PackageManagement.MetaProvider.PowerShell.OptionCategory] 
        $category
    )
}

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. If an exception is thrown from this function, the provider will not be loaded.

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(
    [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, it should throw an exception. If there are no dynamic options for the category, this must not throw an exception.

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:

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 ResolvePackageSources(NuGetRequest request)
function Resolve-PackageSource { 
  param(     
    )
}

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: GetPackageSources

Description

Gets 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 GetPackageSources(Request request);
function Get-PackageSources{ 
  param(
  )
}

Parameters

None.

Additional Options

None.

Response

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

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

Add a custom footer

Concepts

Archive

Clone this wiki locally