Send a command

Send commands using P4 API for .NET methods

To send commands to the P4 Server, your client can use P4 API for .NET methods.

p4 changes command

Copy

// set the options for the p4 changes command
string clientName = "admin_space";
int maxItems = 5;
string userName = "admin";
ChangesCmdOptions options = new ChangesCmdOptions(ChangesCmdFlags.LongDescription,
    clientName, maxItems, ChangeListStatus.None, userName);

// run the command against the current repository
IList<Changelist> changes = rep.getChangelists(options, null);

// changes will contain the data returned by the command
// p4 changes -L -c admin_space -m 5 -u admin

p4 edit command

Copy

// set the options for the p4 edit command
string depotPath = "//depot/main/test.txt";
int changelist = 0;
// create FileSpec with null for ClientPath, LocalPath, and VersionSpec
FileSpec fileToCheckout = new FileSpec(new DepotPath(depotPath), null, null, null)
// using null for FileType
EditCmdOptions options = new EditCmdOptions(EditFilesCmdFlags.None, changelist, null);

// run the command with the current connection
IList<FileSpec> filesCheckedOut = con.Client.EditFiles(options, fileToCheckout);

// filesCheckedOut will contain the data returned by the command
// p4 edit //depot/main/test.txt
// and the file will be checked out in the default pending changelist

p4 submit command

Copy

// set the options for the p4 submit command
// 0 to specify default pending changelist, null for changelist since we are using the default
string description = "update to test.txt";
// set reopen to false
ClientSubmitOptions clientOptions = new ClientSubmitOptions(false,SubmitType.SubmitUnchanged)
SubmitCmdOptions options = new SubmitCmdOptions(SubmitFilesCmdFlags.None,
             0, null, description, clientOptions)
// create FileSpec with null for ClientPath, LocalPath, and VersionSpec
string depotPath = "//depot/main/test.txt";
FileSpec fileToSubmit = new FileSpec(new DepotPath(depotPath), null, null, null)

// run the command with the current connection
SubmitResults results= con.Client.SubmitFiles(options, fileToSubmit);

// results will contain the data returned by the command
// p4 submit -d "update to test.txt" //depot/main/test.txt

Run commands directly

To run commands that do not have methods in the .NET API, your client can use the P4Command.Run() method.

Running command methods is more useful when you care about the results of the command and want them parsed for display or to be passed on to other commands. If command results are not important, running the command directly may be preferable.

For example:

Copy

// create a new command using parameters:
// repository, command, tagged, arguments
string file="//depot/main/test.txt";
P4Command cmd = new P4Command(rep, "attribute", true, file);
Options opts = new Options();
opts["-n"] = "fileID";
opts["-v"] = "1";

//run command and get results
P4CommandResult results = cmd.Run(opts);

// results will contain the data returned by the command
// p4 -ztag attribute -n fileID -v 1 //depot/main/test.txt

Working with Options

Options have subclasses specific to particular commands. These dictionary objects can also be created directly, for example:

Copy

ClientCmdOptions clientOpts = new ClientCmdOptions(ClientCmdFlags.Output);

will create the same options as:

Copy

Options opts = new Options();
opts["-o"]=null;

A command run with either of these options will use the -o flag. Refer to the Options Constructors for details on specific options flags.

Some option flags are mutually exclusive and using them together will result in the same errors that would be returned from the command line.

Examples of correct usage:

Copy

// the SubmitCmdOptions class
public SubmitCmdOptions(SubmitFilesCmdFlags flags, int changelist, Changelist newChangelist,
string description, ClientSubmitOptions submitOptions)

// options for submitting from the default changelist
// the SubmitCmdOptions and ClientSubmitOptions can vary
SubmitCmdOptions submitOpts = new SubmitCmdOptions(SubmitFilesCmdFlags.None, 0, null, "submitting
from default changelist", new ClientSubmitOptions(false,SubmitType.SubmitUnchanged))

// options for submitting from a numbered changelist 16
// the SubmitCmdOptions and ClientSubmitOptions can vary

SubmitCmdOptions submitOpts = new SubmitCmdOptions(SubmitFilesCmdFlags.IncludeJobs, 16, null,
null, new ClientSubmitOptions(false,SubmitType.RevertUnchanged));

// options for submitting a new changelist using a changelist specification where change
// is a P4.Changelist
// the SubmitCmdOptions and ClientSubmitOptions can vary
SubmitCmdOptions submitOpts = new SubmitCmdOptions(SubmitFilesCmdFlags.ReopenFiles, 0, change,
null, new ClientSubmitOptions(true,SubmitType.SubmitUnchanged));
 
// options for submitting a shelved file from a numbered changelist 18
// the SubmitCmdOptions and ClientSubmitOptions can vary
SubmitCmdOptions submitOpts = new SubmitCmdOptions(Perforce.P4.SubmitFilesCmdFlags.SubmitShelved,
18, null, null, null);

Example of incorrect usage

Here is an example of improper usage of flags that are mutually exclusive:

Copy

// the SubmitCmdOptions class
public SubmitCmdOptions(SubmitFilesCmdFlags flags, int changelist, Changelist newChangelist,
string description, ClientSubmitOptions submitOptions)

// improper options for submitting from a numbered changelist 20
// the SubmitCmdOptions and ClientSubmitOptions can vary
SubmitCmdOptions submitOpts = new SubmitCmdOptions(SubmitFilesCmdFlags.None, 16, null,
"submitting change 20", new ClientSubmitOptions(false,SubmitType.RevertUnchanged));

Get progress for supported commands

Configure the submission options, specify the file to submit, and track progress using a custom handler. For more information, see the P4 API for C/C++ documentation.

Description

The ProgressHandler in P4 API for .NET provides access to progress indicators from the P4 Server.

To receive progress events, create a ProgressHandler instance and set it on your connection before running any command that supports progress.

You must implement all five of the following delegates in your handler:

Init
Description
Total
Update
Done

Each delegate will be called by the API as the server reports progress. You can use these to update a UI, log progress, or monitor long-running operations.

Handler Delegates

Method	Description
`Init(int type) -> void`	This method initializes the progress indicator. The `type` parameter defines the kind of progress (for example, file transfer or computation).
`Description(string desc, int units)-> void`	This method provides a textual description of the progress being tracked and the unit of measurement (for example, bytes or files).
`Total(long total)-> void`	This method sets the total number of units to expect. This is typically used when there is a defined target value, allowing progress to be tracked and displayed, such as in a progress bar.
`Update(long position)-> void`	The `Update(long position)` method is invoked whenever there is a progress update. If `Total(long total)` has not been called, this method can be used to indicate ongoing activity, such as displaying a spinner or other visual feedback to show that work is in progress.
`Done(bool failed)-> void`	This method is invoked when the progress context has completed. If failed is `true`, it indicates that an error occurred and the operation was unsuccessful; otherwise, the operation was completed successfully.

Progress Units and Progress Types stays same as mentioned for P4 API for C/C++I. For more information, see the P4 API for C/C++ documentation.

Example

Copy

// Set the options for the p4 submit command
// 0 to specify default pending changelist, null for changelist since we are using the default
string description = "update to test.txt";
ClientSubmitOptions clientOptions = new ClientSubmitOptions(false, SubmitType.SubmitUnchanged);
SubmitCmdOptions options = new SubmitCmdOptions(
    SubmitFilesCmdFlags.None,
    0, null, description, clientOptions);

// Create FileSpec for the file to submit
string depotPath = "//depot/main/test.txt";
FileSpec fileToSubmit = new FileSpec(new DepotPath(depotPath), null, null, null);

// Create a progress handler to receive progress events.
// Progress events include: Init, Description, Total, Update, and Done.
ProgressHandler progressHandler = new ProgressHandler
{
    Init = (type) => Console.WriteLine($"Progress initialized with type: {type}"),
    Description = (desc, units) => Console.WriteLine($"Progress description: {desc} (units: {units})"),
    Total = (total) => Console.WriteLine($"Total work: {total}"),
    Update = (position) => Console.WriteLine($"Progress updated: {position}"),
    Done = (failed) => Console.WriteLine(failed ? "Progress failed." : "Progress completed successfully.")
};

// Set the progress handler on the connection
con.SetProgressHandler(progressHandler);

// Run the submit command with progress reporting
SubmitResults results = con.Client.SubmitFiles(options, fileToSubmit);

// results will contain the data returned by the command
// p4 submit -d "update to test.txt" //depot/main/test.txt

Build a FileSpec

Commands for working with files and paths will need a FileSpec or a list or an array of FileSpec as an argument when running the command. A FileSpec consists of a PathSpec (or PathSpecs) and a VersionSpec. The PathSpecs can be DepotPaths, ClientPaths, and LocalPaths. The VersionSpec can be a revision or a revision range. Refer to the VersionSpec class for additional revision types.

Example FileSpecs:

Copy

// create a FileSpec for //depot/test.txt
// using new FileSpec(PathSpec path, VersionSpec version)
PathSpec path = new DepotPath("//depot/test.txt");
FileSpec depotFile = new FileSpec(path, null);

// create a FileSpec for //depot/test.txt#5
// using new FileSpec(PathSpec path, VersionSpec version)
path = new DepotPath("//depot/test.txt");
VersionSpec version = new Revision(5);
depotFile = new FileSpec(path, version);

// create a FileSpec for //depot/test.txt@16,@22
// (version range between changelists 16 and 22)
// using new FileSpec(PathSpec path, VersionSpec version)
path = new DepotPath("//depot/test.txt");
VersionSpec lowerChangeID = new ChangelistIdVersion(16);
VersionSpec upperChangeID = new ChangelistIdVersion(22);
version = new VersionRange(lowerChangeID,upperChangeID);
depotFile = new FileSpec(path, version);

// create a FileSpec for C:\Users\username\Depot\test.txt#head
// using new FileSpec(PathSpec path, VersionSpec version)
path = new LocalPath("C:\\Users\\username\\Depot\\test.txt");
version = new HeadRevision();
depotFile = new FileSpec(path, version);

// create a FileSpec for //depot/test.txt@labelName
// using new FileSpec(PathSpec path, VersionSpec version)
path = new DepotPath("//depot/test.txt");
version = new LabelNameVersion("labelName");
depotFile = new FileSpec(path, version);

// create a FileSpec for //depot/...@2013/5/27,@now
// (version range between 2013/5/27 and now)
// using new FileSpec(PathSpec path, VersionSpec version)
path = new DepotPath("//depot/...");
DateTimeVersion lowerTimeStamp = new DateTimeVersion(new DateTime(2013,5,27));
DateTimeVersion upperTimeStamp = new DateTimeVersion(DateTime.Now);
version = new VersionRange(lowerTimeStamp,upperTimeStamp);
depotFile = new FileSpec(path, version);;

Print file contents

There are two methods you can use to print file contents:

GetFileContents - Use this method to print file contents in text format only.
GetFileContentsEx - Use this method to print file contents in text and binary format.

Depending on the workspace setting for LineEnd determines which methods need to be used to get an output. For more information, see Send a command.

GetFileContents

Use this method is to print file contents in text format only. The method checks the base type of the file stored in the depot.

This method does not print content from files in a binary format. If used on binary files, the printed output may be incomplete or invalid.

Only use this method if you are certain the target files are stored as text.

Example GetFileContents:

Copy

PathSpec path = new DepotPath("//depot/file.txt");
FileSpec depotFile = new FileSpec(path, null);
IList<string>  result = p4.GetFileContents(null,depotFile);

GetFileContentsEx

Use this method to print file contents in text and binary format. Use this method if you do not know the file type of the target files in the depot.

Example GetFileContentsEx:

Copy

PathSpec path = new DepotPath("//depot/file.txt");
FileSpec depotFile = new FileSpec(path, null);
IList<object>  result = p4.GetFileContentsEx(null,depotFile);