PackageProvider Interface

A OneGet PackageProvider that is implemented in PowerShell must be written as a module that exposes functions with signatures that match the following:

Overview (c#)

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

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

int StartFind(Callback c);
bool CompleteFind(int id, Callback c);

void FindPackage(string name, string requiredVersion, string minimumVersion, string maximumVersion, int id, Request r)
void FindPackageByFile(string file, int id, Request request)
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)

Try out a sample provider: https://github.com/OneGet/MyAlbum-Sample-Provider

Required Methods

Method: GetPackageProviderName

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 GetPackageProviderName()

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.

Optional Methods

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, bool validateLocation, Request request)

function Add-PackageSource { 
  param(
    [string] $name,      
    [string] $location,  
    [bool] $trusted,     
    [bool] $validateLocation 
    )
} 

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
validateLocation	bool	If true, indicates the location should be validated (verified to be an actual workable location) before it is added as a 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: FindPackageByName

Description

Finds packages given

Necessity

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

Syntax

void FindPackageByName(string name, string requiredVersion, string minimumVersion, string maximumVersion, Request request);

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

# Alternative, accepts multiple names as first parameter
function Find-PackageByName { 
  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

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 filePath, 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.

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, Request request);

function Get-InstalledPackages{ 
  param(
    [string] $name   
    )
}

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.

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: 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: 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: 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: 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. (ie, 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. (ie, 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.