<?xml version="1.0" encoding="utf-8"?>
<topic id="af6b5020-31c0-491f-b8c8-a803ae388198" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<content>
<legacyBold>Pre-requisites</legacyBold>
<para>For a project to use P4API.NET, p4api.net.dll and p4bridge.dll must be in the build output directory.
On creation of a new console application, the Debug output location would be: ...\SolutionDir\ProjectDir\bin\Debug\.
Next, add p4api.net.dll as a project reference by clicking Add Reference... on the References node of the
project in the solution explorer in Visual Studio and browsing to the location of the newly added p4api.net.dll.</para>
<para><markup><br/><br/></markup></para>
<legacyBold>Using P4API.NET</legacyBold>
<para>Client programs interact with the Perforce server by:</para>
<list class="ordered">
<listItem><para>Initializing a connection.</para></listItem>
<listItem><para>Sending commands.</para></listItem>
<listItem><para>Closing the connection.</para></listItem>
<para></para>
</list>
<para><markup><br/><br/></markup></para>
<legacyBold>Initializing a connection</legacyBold>
<para>To connect to the Perforce server, your client application must call the Connect() method; for example: </para>
<code>
// initialize the connection variables
// note: this is a connection without using a password
string uri = "localhost:6666";
string user = "admin";
string ws_client = "admin_space";
// define the server, repository and connection
Server server = new Server(new ServerAddress(uri));
Repository rep = new Repository(server);
Connection con = rep.Connection;
// use the connection variables for this connection
con.UserName = user;
con.Client = new Client();
con.Client.Name = ws_client;
// connect to the server
con.Connect(null);
</code>
<code>
// initialize the connection variables
// note: this is a connection without using a password
// that sets the application name and version.
// This information will appear when commands are
// recorded in the server log as
// [ProgramName/ProgramVersion]
string uri = "localhost:6666";
string user = "admin";
string ws_client = "admin_space";
// define the server, repository and connection
Server server = new Server(new ServerAddress(uri));
Repository rep = new Repository(server);
Connection con = rep.Connection;
// use the connection variables for this connection
con.UserName = user;
con.Client = new Client();
con.Client.Name = ws_client;
// set the program name and version
P4.Options options = new P4.Options();
options["ProgramName"] ="MyP4API.NET_APP";
options["ProgramVersion"] ="2015.1.105.4164";
// connect to the server
con.Connect(options);
</code>
<code>
// initialize the connection variables
// note: this is a connection using a password
string uri = "localhost:6666";
string user = "admin";
string ws_client = "admin_space";
string pass = "password";
// define the server, repository and connection
Server server = new Server(new ServerAddress(uri));
Repository rep = new Repository(server);
Connection con = rep.Connection;
// use the connection variables for this connection
con.UserName = user;
con.Client = new Client();
con.Client.Name = ws_client;
// connect to the server
con.Connect(null);
// login to the server to get credential
// (using null for options and user params)
Credential cred = con.Login(pass, null, null);
// get server metadata and check version
// (using null for options parameter)
ServerMetaData p4info = rep.GetServerMetaData(null);
ServerVersion version= p4info.Version;
string release = version.Major;
</code>
<para>For information on SSL connections, refer to the <see cref="M:Perforce.P4.Connection.TrustAndConnect">TrustAndConnect method.</see>
</para>
<para><markup><br/><br/></markup></para>
<legacyBold>Setting Command Time Out</legacyBold>
<para>
The Command Time Out duration defaults to 5 seconds. If a command times out, P4API.NET will throw a P4CommandTimeOutException.
After a connection has been established the Command Time Out can be changed in Repository.Connection.CommandTimeout:
</para>
<code>
// initialize the connection variables
// note: this is a connection without using a password
string uri = "localhost:6666";
string user = "admin";
string ws_client = "admin_space";
// define the server, repository and connection
Server server = new Server(new ServerAddress(uri));
Repository rep = new Repository(server);
Connection con = rep.Connection;
// use the connection variables for this connection
con.UserName = user;
con.Client = new Client();
con.Client.Name = ws_client;
// connect to the server
con.Connect(null);
// change the Command Time Out to 20 seconds
con.CommandTimeout = TimeSpan.FromSeconds(20);
</code>
<para>
<markup>
<br/>
<br/>
</markup>
</para>
<legacyBold>Sending commands</legacyBold>
<para>To send commands to the Perforce server, your client can use P4 API.NET methods; for example: </para>
<code>
// 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);
// changes will contain the data returned by the command
// p4 changes -L -c admin_space -m 5 -u admin
</code>
<code>
// 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
</code>
<code>
// 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
</code>
<para><markup><br/><br/></markup></para>
<legacyBold>Closing the connection</legacyBold>
<para>To disconnect from the Perforce server, your client application must call the Disconnect() method; for example: </para>
<code>
// disconnect from the server
con.Disconnect();
</code>
<para><markup><br/><br/></markup></para>
<legacyBold>Running commands directly</legacyBold>
<para>To run commands that do not have methods in the .NET API, your client can use the P4Command.Run() method; for example: </para>
<code>
// 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
</code>
<para>Running command methods is more useful when 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.</para>
<para><markup><br/><br/></markup></para>
<legacyBold>Working with Options</legacyBold>
<para>Options have subclasses specific to particular commands. These dictionary objects can also be created directly,
for example: </para>
<code>
ClientCmdOptions clientOpts = new ClientCmdOptions(ClientCmdFlags.Output);
</code>
<para><markup><br/></markup></para>
will create the same options as:
<para><markup><br/></markup></para>
<code>
Options opts = new Options();
opts["-o"]=null;
</code>
<para><markup><br/></markup></para>
A command run with either of these options will use the -o flag. Refer to the Options Constructors for details on
specific options flags.
<para><markup><br/></markup></para>
Note that some option flags are mutually exclusive and using them together will result in the same errors
that would be returned from the command line. Some examples of proper usage:
<para><markup><br/></markup></para>
<code>
// 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);
</code>
<para>
<markup>
<br/>
</markup>
</para>
Here is an example of improper usage of flags that are mutually exclusive:
<para>
<markup>
<br/>
</markup>
</para>
<code>
// 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));
</code>
<para>
<markup>
<br/>
</markup>
</para>
The above options will return the error "Usage: submit [ -r -f option ] -c changelist#\n"
because a changelist number and a description were specified and the -c and -d flags
are mutually exclusive.
<para><markup><br/><br/></markup></para>
<legacyBold>Building a FileSpec</legacyBold>
<para>Commands for working with files and paths will need a FileSpec or a list or an array of FileSpecs 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. Some examples: </para>
<code>
// 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);
</code>
<para><markup><br/></markup></para>
Refer to the VersionSpec class for additional revision types.
<para><markup><br/><br/></markup></para>
<legacyBold>Error handling</legacyBold>
<para>If a command returns a null, there were likely errors. Errors have different severity levels and do
not necessarily mean that a command has failed. P4 API.NET methods will throw a P4Exception if an error of
severity E_FAILED or higher is returned. This setting can be changed in P4Exception.MinThrowLevel. For
example:</para>
<code>
// turn off P4Exceptions
P4Exception.MinThrowLevel = ErrorSeverity.E_NOEXC;
</code>
<para><markup><br/></markup></para>
The following is an example of a command that will throw a P4Exception:
<para><markup><br/></markup></para>
<code>
try
{
// set options for client command
ClientCmdOptions clientOpts = new ClientCmdOptions(ClientCmdFlags.Switch);
// attempt to get label with p4 -s label testLabel
Label label = rep.GetLabel("testLabel", null, clientOpts);
}
catch (P4Exception ex)
{
// catch exception and display error message
Console.WriteLine(ex.Message);
}
</code>
<para><markup><br/></markup></para>
Because the error that the command returns is of severity E_FAILED an exception will be thrown. The
Message displayed is:
Usage: label [ -d -f -g -i -o -t template ] labelname
Invalid option: -s.
since there is no -s flag for p4 label.
<para><markup><br/></markup></para>
This is an example of a command that will not throw a P4Exception:
<para><markup><br/></markup></para>
<code>
// set options for client command
try
{
SyncFilesCmdOptions syncOpts = new SyncFilesCmdOptions(SyncFilesCmdFlags.None, 1);
FileSpec depotFile = new FileSpec(new DepotPath("//depot/test.txt"), null, null, null);
IList<FileSpec> syncedFiles = rep.Connection.Client.SyncFiles(syncOpts, depotFile);
}
catch (P4Exception ex)
{
Console.WriteLine(ex.Message);
}
</code>
<para><markup><br/></markup></para>
Because the error that the command returns is of severity E_WARN no exception will be thrown. The
file, //depot/test.txt is already at the latest revision but the command has still succeeded with
a warning of "//depot/test.txt - file(s) up-to-date." syncedFiles will be null.
<para><markup><br/><br/></markup></para>
<legacyBold>Sample application: a console specification fetcher</legacyBold>
<para>This is a console application that connects to a Perforce server and returns Perforce specification information
based on user input of 2 words: specification type, specification name. It uses Connection.Login(password) for working
with a server at security level 3. Lower security levels should also work and connecting with a user without a password
can be done by passing a blank string for password. There is minimal error handling for failed Perforce commands. Since
-o is used, specifications that do not yet exist may be returned on entry of a non-existent specification name.</para>
<para><markup><br/><br/></markup></para>
<para>Create a new C# Console Application project and paste the following code into Program.cs:</para>
<code>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Perforce.P4;
namespace apiConsoleApplication
{
class Program
{
static void Main()
{
string uri = "";
string user = "";
string workspace = "";
string pass = "";
bool exit = false;
Server server = new Server(new ServerAddress(uri));
Repository rep = new Repository(server);
// establish a connection to a server
while(rep.Connection.Status==ConnectionStatus.Disconnected)
{
// get user input for connection
Console.WriteLine("port:");
uri = Console.ReadLine();
Console.WriteLine("");
Console.WriteLine("user:");
user = Console.ReadLine();
Console.WriteLine("");
Console.WriteLine("client:");
workspace = Console.ReadLine();
Console.WriteLine("");
Console.WriteLine("password:");
pass = Console.ReadLine();
Console.WriteLine("");
server = new Server(new ServerAddress(uri));
rep = new Repository(server);
Connection con = rep.Connection;
con.UserName = user;
con.Client = new Client();
con.Client.Name = workspace;
// connect
bool connected = con.Connect(null);
if (connected)
{
try
{
// attempt a login
Credential cred = con.Login(pass);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
con.Disconnect();
continue;
}
// get p4 info and show successful connection
ServerMetaData info = rep.GetServerMetaData(null);
Console.WriteLine("CONNECTED TO " + info.Address.Uri);
Console.WriteLine("");
}
else
{
// retry the prompt for connection info
continue;
}
}
while(rep.Connection.Status==ConnectionStatus.Connected&&!(exit))
{
Options opts= new Options();
opts["-o"] = null;
string input = Console.ReadLine();
exit = (input == "exit");
string[] command = input.Split(' ');
switch (command[0])
{
// on user input of job <job name> get job
// and output to console
case "job":
try
{
Job job = rep.GetJob(command[1], opts);
Console.WriteLine("");
Console.WriteLine(job.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
// on user input of change <change number> get
// change and output to console
case "change":
try
{
opts = new Options();
int id = 0;
int.TryParse(command[1], out id);
Changelist change = rep.GetChangelist(id, opts);
Console.WriteLine("");
Console.WriteLine(change.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
// on user input of client <client name> get
// client and output to console
case "client":
try
{
Client client = rep.GetClient(command[1]);
Console.WriteLine("");
Console.WriteLine(client.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
// on user input of label <label name> get
// label and output to console
case "label":
try
{
Label label = rep.GetLabel(command[1]);
Console.WriteLine("");
Console.WriteLine(label.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
// on user input of stream <stream path>get
// stream and output to console
case "stream":
try
{
Stream stream = rep.GetStream(command[1]);
Console.WriteLine("");
Console.WriteLine(stream.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
// on user input of branch <branch name> get
// branch and output to console
case "branch":
try
{
BranchSpec branch = rep.GetBranchSpec(command[1]);
Console.WriteLine("");
Console.WriteLine(branch.ToString());
Console.WriteLine("");
break;
}
catch (Exception ex)
{
Console.WriteLine("");
Console.WriteLine(ex.Message);
Console.WriteLine("");
break;
}
}
}
}
}
}
</code>
</content>
</developerConceptualDocument>
</topic>