Il presente articolo è stato tradotto automaticamente.

ALM Rangers

Controllo della versione nel modello a oggetti client di TFS

Jeff Bramwell

Scarica il codice di esempio

Questo articolo è il seguito di "Utilizzando the Team Foundation Server Client Object Model," scritti dai membri di Visual Studio ALM Rangers nel numero di agosto 2012 (msdn.microsoft.com/magazine/jj553516). Finora, abbiamo introdotto il modello di oggetto client di Team Foundation Server (TFS), e ora I'll introdurre il controllo della versione di API.

Per ricapitolare, i Rangers ALM sono un gruppo di esperti che promuove la collaborazione tra il gruppo di prodotti Visual Studio, Microsoft Services e la comunità Microsoft più Valuable Professional (MVP) di indirizzamento funzionalità mancante, rimozione bloccanti di adozione e la pubblicazione di buone pratiche e indicazioni basate su esperienze reali.

Se qualcuno dovesse chiederti di spiegare che cosa è TFS, le probabilità sono che si parla di controllo della versione entro il primo paio di frasi. Anche se il controllo della versione di giocare un ruolo importante all'interno di TFS, si può vedere Figura 1 che non c'è molto di più di TFS. Come con molte funzioni all'interno di TFS, il sottosistema di controllo versione è accessibile tramite il modello a oggetti di TFS. Questa accessibilità vi offre un modello di estendibilità che è possibile sfruttare all'interno dei propri processi e strumenti personalizzati.

Figura 1 Team Foundation Server caratteristiche

Gli assembly e gli spazi dei nomi

Prima di poter accedere alle funzionalità fornite all'interno del modello di oggetto TFS, è necessario prima capire gli assembly richiesti e gli spazi dei nomi. Ricorderete che il primo articolo utilizzato lo spazio dei nomi Microsoft.TeamFoundation.Client. Questo spazio dei nomi contiene le classi e i metodi necessari per la connessione a un server di configurazione TFS ed è situato all'interno dell'assembly con lo stesso nome. Questo spazio dei nomi è centrale per sviluppo correlati a modello oggetto TFS tutti.

Quando si lavora con controllo della versione, noi dobbiamo utilizzare anche lo spazio dei nomi Microsoft. Questo spazio dei nomi contiene le classi necessarie per l'interazione con il sistema di controllo versione TFS. Utilizzando le API all'interno di questo spazio dei nomi consente di accedere a file e cartelle, modifiche in sospeso, unioni, rami e così via. Il VersionControlServer all'interno di questo spazio dei nomi è la classe principale che fornisce l'accesso al repository di controllo versione TFS.

Un semplice esempio per iniziare

La classe VersionControlServer espone molte proprietà, metodi ed eventi per interagire con il controllo della versione all'interno di TFS. Comincerò con un semplice esempio: recuperare l'ID dell'ultimo changeset.

I tre passaggi di base necessari per interagire con la maggior parte delle API esposte dal modello a oggetti TFS sono:

1. Connettersi a un server di configurazione TFS.
2. Ottenere un riferimento al servizio TFS che si prevede di utilizzare.
3. Fare uso di varie proprietà, metodi ed eventi forniti dal servizio.

Un approccio leggermente diverso alla connessione a TFS, in contrasto con gli esempi presentati in questo articolo di agosto, sto andando a collegare al TFS utilizzando la classe TeamProjectPicker. La classe TeamProjectPicker viene visualizzata una finestra di dialogo standard per la connessione al server TFS. Questa classe non è solo utile per le applicazioni full-optional, ma è anche molto utile per semplice utilità dove potrebbe essere necessario passare tra più istanze di TFS.

Creare una nuova istanza di TeamProjectPicker e visualizzare utilizzando il metodo ShowDialog:

private TfsTeamProjectCollection _tpc;
using (var picker = new 
  TeamProjectPicker(TeamProjectPickerMode.NoProject, false))
{
  if (picker.ShowDialog()== DialogResult.OK)
  {
    _tpc = picker.SelectedTeamProjectCollection;
  }
}

Questo codice verrà visualizzata una finestra di dialogo simile a quella mostrata Figura 2.

Nella figura 2 la finestra di dialogo TeamProjectPicker

Facendo clic su Connetti restituirà un'istanza di TfsTeamProject­insieme che rappresenta il selezionato Team Project Collection (TPC). Se si preferisce utilizzare un approccio più programmatico (cioè, nessuna interazione utente) per connettersi a TFS, rinviare l'articolo di agosto per ulteriori esempi.

Una volta che hai ottenuto un riferimento a un As, può essere utilizzato per ottenere un'istanza del servizio VersionControlServer:

var vcs = _tpc.GetService<VersionControlServer>();

Una volta che hai un riferimento al servizio si può fare uso dei metodi esposti dal servizio:

var latestId = vcs.GetLatestChangesetId();

Questo è un esempio semplice, ma lo dimostrano i passaggi di base per l'interazione con il sistema di controllo versione in TFS. Tuttavia, alcune applicazioni sono questo semplice.

"Sempre più tardi"

Uno scenario comune relative al controllo di versione è ottenere l'ultimo codice sorgente dal repository — che è, "sempre più recenti." Mentre lavorava all'interno di Visual Studio, si ottiene in genere l'ultimo codice sorgente facendo clic su un file o una cartella all'interno di Source Control Explorer (SCE) e selezionando Leggi ultima versione. Per poter funzionare correttamente, è necessario anche un'area di lavoro mappata selezionato. Quando il download del codice sorgente più recente dal server, il workspace selezionato determina dove verranno archiviato.

Seguire questi passaggi per ottenere a livello di codice il codice sorgente più recente:

1. Connettersi a un server di configurazione TFS.
2. Ottenere un riferimento al servizio di controllo di versione.
3. Utilizzare un'area esistente o creare un'area di lavoro temporanea, nuovo.
4. Mappa dell'area di lavoro in una cartella locale.
5. Scaricare i file desiderati dall'area di lavoro.

Basandosi sull'esempio precedente, aggiungere il codice riportato Figura 3.

Figura 3 Get ultime dal controllo della versione

// Create a temporary workspace
var workspace = vcs.CreateWorkspace(Guid.NewGuid().ToString(),
  _tpc.AuthorizedIdentity.UniqueName,
  "Temporary workspace for file retrieval");
// For this workspace, map a server folder to a local folder
workspace.Map("$/Demo/TFS_VC_API", @"C:\Dev\Test");
// Create an ItemSpec to determine which files and folders are retrieved
// Retrieve everything under the server folder
var fileRequest = new GetRequest(
  new ItemSpec("$/Demo/TFS_VC_API", RecursionType.Full),
  VersionSpec.Latest);
// Get latest
var results = workspace.Get(fileRequest, 
  GetOptions.GetAll | GetOptions.Overwrite);

Se esiste già un'area di lavoro e si desidera utilizzarlo, sostituire linee 1-4 in Figura 3 con il seguente:

// Get a reference to an existing workspace,
// in this case, "DEMO_Workspace"
var workspace = vcs.GetWorkspace("DEMO_Workspace",
  _tpc.AuthorizedIdentity.UniqueName);

Nota che se non conoscete il nome dell'area di lavoro o non voglio specificarlo, è possibile chiamare GetWorkspace (vedi precedente esempio di codice), passando solo un percorso locale. Verrà restituito l'area di lavoro mappata a percorso locale.

Non è necessario mappare l'area di lavoro a livello di codice, quindi è possibile anche rimuovere linee 5 e 6.

Individuare i file e le cartelle per il Download

Come ci si potrebbe aspettare, molte delle API fornite da TFS consentono di interrogare il server di controllo di versione per elementi specifici, come pure le versioni specifiche di elementi. Nell'esempio precedente, quando ho creato una nuova istanza di GetRequest, ho dovuto fornire un'istanza di ItemSpec. Un ItemSpec, abbreviazione di elemento specifica, descrive un insieme di file o cartelle. Questi elementi possono essere presenti sul computer locale o nel server del controllo della versione. In questo esempio specifico, sto costruendo un ItemSpec per restituire tutti i file all'interno della cartella del server "$, Demo, TFS_VC_API."

Il secondo parametro nel costruttore ItemSpec usato qui specifica RecursionType, che nessuno, può essere pieno o UnLivello. Questo valore determina quanti livelli profondi un'API dovrebbe prendere in considerazione quando si eseguono query elementi. Specificando un RecursionType di UnLivello sarà una query o restituire oggetti da solo il livello più alto (rispetto al ItemSpec). Un valore di pieno sarà query o restituire oggetti dal più alto livello, nonché a tutti i livelli inferiori (ancora una volta, rispetto al ItemSpec).

Considerando che un ItemSpec determina gli elementi da prendere in considerazione in base a nome e posizione quando si eseguono query il sistema di controllo versione, un VersionSpec, specifica della versione breve per, fornisce la possibilità di limitare il set di item basato sulla versione. Versione­Spec è una classe astratta non può essere istanziata direttamente. TFS fornisce diverse implementazioni della versione­Spec che si può fare uso di quando una query il sistema di controllo versione. Figura 4 elenca le varie implementazioni di VersionSpec fornito dalla scatola con TFS 2012.

Figura 4 tipi di VersionSpec

Tornando all'esempio precedente della creazione di un GetRequest, specificato versionspec come mia specifica versione. Versionspec è semplicemente un riferimento a un'istanza singleton della LatestVersionSpec forniti solo per comodità. Per recuperare il codice basato su un'etichetta specifica, ad esempio, creare un'istanza di LabelVersionSpec:

var fileRequest = new GetRequest(
  new ItemSpec("$/Demo/TFS_VC_API", RecursionType.Full),
  new LabelVersionSpec("MyLabel"));

Check-out Code

Ora che sapete come identificare e recuperare gli elementi specifici da server di controllo della versione, diamo un'occhiata a come è possibile controllare il codice sorgente. In termini TFS, per verificare un elemento è pend una modifica su tale elemento. Per sospendere una modifica su elementi all'interno di un'area di lavoro particolare, si chiama il Metodo Workspace.PendEdit. Il metodo PendEdit ha nove overload, che richiedono un percorso o una matrice di percorsi così come alcuni altri parametri facoltativi. Uno dei parametri opzionali è RecursionType, che funziona esattamente come descritto in precedenza per ItemSpec.

Ad esempio, per estrarre tutti i file c# (CS), effettuare la chiamata:

// This example assumes we have obtained a reference
// to an existing workspace by following the previous examples
var results = workspace.PendEdit("$/Demo/TFS_VC_API/*.cs", 
  RecursionType.Full);

In questo esempio, io sto chiedendo che TFS pend modifiche su tutti i file c# (via il jolly *.cs) sotto la cartella del server "$, Demo, TFS_VC_API." Perché io sto specificando un RecursionType di piena, potrai verificare file c# in tutte le cartelle sotto il percorso specificato. La firma del metodo specifico utilizzata in questo esempio anche scaricare i file estratti nel percorso locale come mappato per l'area di lavoro specificata. È possibile utilizzare una delle versioni di overload di questo metodo che accetta un argomento di tipo PendChangesOptions e specificare PendChangesOption.Silent per sopprimere il download di file quando il modifiche in sospeso. Il valore restituito in risultati contiene un numero di elementi scaricati a causa della chiamata a PendEdit.

Le modifiche non sono l'unica azione che potete pend all'interno del sistema di controllo versione. Ci sono anche metodi per in sospeso:

• Aggiunge via PendAdd
• Rami via PendBranch As
• Elimina via PendDelete
• Proprietà via PendPropertyName
• Rinomina via PendRename
• Undeletes via PendUndelete As

Ad esempio, il seguente codice Commmissione un nuovo ramo, denominata Dev, dalla cartella principale:

// This example assumes we have obtained a reference
// to an existing workspace by following the previous examples
var results = workspace.PendBranch("$/Demo/TFS_VC_API/Main",  
   "$/Demo/TFS_VC_API/Dev", VersionSpec.Latest);

Riguarderemo diramazione e l'Unione utilizzando le API più dettagliatamente in un prossimo articolo.

Archiviazione delle modifiche

Una volta che hai apportato modifiche a uno o più dei file estratti, potete controllarli di nuovo tramite il Metodo Workspace.CheckIn. Prima di chiamare il metodo CheckIn, tuttavia, è necessario prima ottenere un elenco di modifiche per l'area di lavoro in sospeso chiamando Workspace.GetPendingChanges. Se non si specifica alcun parametro per il metodo GetPendingChanges, avrai indietro tutte le modifiche in sospeso per l'area di lavoro. In caso contrario, si può fare uso di uno degli altri 11 overload e filtrare l'elenco di modifiche restituito dalla chiamata a TFS in sospeso.

Nell'esempio seguente si verificherà in tutte le modifiche in sospeso per l'area di lavoro:

// This example assumes we have obtained a reference
// to an existing workspace by following the previous examples
var pendingChanges = workspace.GetPendingChanges();
var results = workspace.CheckIn(pendingChanges, "My check in.");

Nella prima riga di codice, sto diventando un elenco di tutte le modifiche in sospeso per l'area di lavoro. Nella seconda riga, controllare tutto nuovo per il server di controllo versione specificando un commento per essere associato con l'insieme di modifiche. Il valore restituito in risultati contiene un conteggio degli elementi checked in. Se c'è una o più modifiche in sospeso e risultati torna come zero, differenze non sono state trovate negli elementi in sospeso tra il server e il client.

Modifiche in sospeso non sono le uniche modifiche controllate al sistema di controllo versione. Verifica anche:

• Aggiunte
• Rami
• Delezioni/Undeletes
• Proprietà
• Rinomina

È inoltre possibile annullare le modifiche in sospeso chiamando il lavoro­spazio.Annullare il metodo. Come con il metodo CheckIn, è necessario anche specificare che le modifiche in sospeso si desidera annullare. Nell'esempio seguente verrà annullare tutte le modifiche in sospeso per l'area di lavoro:

var pendingChanges = workspace.GetPendingChanges();
var results = workspace.Undo(pendingChanges);

Recupero di storia

Un compito comune all'interno di Team Explorer è Guarda la storia di uno o più file o cartelle. Si potrebbe trovare la necessità di fare questo a livello di codice come bene. Come ci si potrebbe aspettare, c'è un'API per l'interrogazione di storia. Infatti, il metodo che ho intenzione di discutere è disponibile dall'istanza di VersionControlServer (come rappresentato dalla variabile vcs negli esempi precedenti). Il metodo è VersionControlServer.QueryHistory, e ha otto overload. Questo metodo offre la possibilità di interrogare il server di controllo di versione in molti modi diversi, a seconda dei tipi e valori dei parametri passati nella chiamata al metodo.

Figura 5 mostra ciò che la vista di storia per il file Form1. cs potrebbe essere simile all'interno della SCE.

Figura 5 storia per Form1. cs

Si può replicare questa funzionalità a livello di codice utilizzando il codice mostrato Figura 6.

Figura 6 recuperare elemento storia

var vcs = _tpc.GetService<VersionControlServer>();
var results = vcs.QueryHistory(
"$/Demo/TFS_VC_API/Form1.cs", // The item (file) to query history for
VersionSpec.Latest,           // We want to query the latest version
0,                            // We're not interested in the Deletion ID
RecursionType.Full,           // Recurse all folders
null,                         // Specify null to query for all users
new ChangesetVersionSpec(1),  // Starting version is the 1st changeset        
                              // in TFS
VersionSpec.Latest,           // Ending version is the latest version
                              // in TFS
int.MaxValue,                 // Maximum number of entries to return
true,                         // Include changes
false);                     // Slot mode
if (results != null)
{
  foreach (var changeset in (IEnumerable<Changeset>)results)
  {
    if (changeset.Changes.Length > 0)
    {
      foreach (var change in changeset.Changes)
      {
        ResultsTextBox.Text +=
          string.Format("  {0}\t{1}\t{2}\t{3}\t{4}\t{5}\r\n",
          change.Item.ChangesetId,
          change.ChangeType,
          changeset.CommitterDisplayName,
          change.Item.CheckinDate,
          change.Item.ServerItem,
          changeset.Comment);
      }
    }
  }
}

Prestare particolare attenzione all'argomento sulla linea 13 in Figura 6. Io sto specificando un valore true per il parametro includeChanges. Se si specifica false, quindi modifiche specifiche per la cronologia non vengano inclusi nei risultati restituiti e il Figura 6 esempio non verranno visualizzati i dettagli. È ancora possibile visualizzare changeset base storia senza restituire le modifiche, ma alcuni dettagli non saranno disponibili.

Esegue la Figura 6 esempio produce i risultati mostrati Figura 7.

Figura 7 storia da API

Ci sono molte altre varianti di chiamare l'API QueryHistory. Per idee su come si potrebbe fare uso di questo metodo, semplicemente giocare con le caratteristiche di storia nella SCE. Può anche eseguire una query molto più di storia. Per esempio, ci sono altri metodi relativi alla query forniti da VersionControlServer, come ad esempio:

• QueryBranchObjectOwnership
• QueryBranchObjects
• QueryLabels
• QueryMergeRelationships
• QueryMerges
• QueryMergesExtended
• QueryMergesWithDetails
• QueryPendingSets
• QueryRootBranchObjects
• QueryShelvedChanges
• QueryShelvesets
• QueryWorkspaces

C'è un sacco di informazioni disponibili dal server del controllo della versione, e i vari metodi di query si forniscono con una finestra in tali informazioni.

Passi successivi

I Rangers hanno cominciato solo a toccare le funzioni di controllo versione esposte dal modello a oggetti TFS. La funzionalità analizzate in questo articolo può essere utile e potente, ma innumerevoli caratteristiche sono esposti dal server del controllo della versione TFS che non abbiamo coperto. Alcuni esempi di queste funzionalità includono diramazioni e Unione, sospensione, le etichette e gli eventi del controllo di versione. Con questa serie di articoli, speriamo di esporre molte di queste API e fornirvi la conoscenza è necessario fare un uso migliore del modello a oggetti TFS. Restate sintonizzati per ulteriori informazioni.

Jeff Bramwell è direttore di architettura enterprise presso Farm Credit Services of America. Ha più di 20 anni di esperienza di sviluppo software e si sforza sempre di seguire il mantra di avvio semplice e il tuo lavoro da lì. Il suo blog è al devmatter.blogspot.com. È possibile seguirlo su Twitter a twitter.com/jbramwell.

Grazie ai seguenti esperti tecnici per la revisione di questo articolo: Brian Blackman, Mike Fourie e Willy-Peter Schaub