• Artigo

Este artigo foi traduzido por máquina.

ALM Rangers

Controle de versão no objeto do cliente do TFS

Jeff Bramwell

Baixar o código de exemplo

Este artigo é uma continuação para "Usando o Team Foundation Server modelo de objeto cliente," escritos pelos membros do Visual Studio ALM Rangers na edição de agosto de 2012 (msdn.microsoft.com/magazine/jj553516). Até agora, nós introduzimos o modelo de objeto de cliente do Team Foundation Server (TFS), e agora eu vou apresentar o APIs de controle de versão.

Recapitulando, os ALM Rangers são um grupo de especialistas que promovem a colaboração entre o grupo de produtos do Visual Studio, Microsoft Services e Microsoft MVP Most Valuable Professional () Comunidade por endereçamento funcionalidade ausente, removendo bloqueadores de adopção e publicação de práticas recomendadas e diretrizes com base nas experiências do mundo real.

Se alguém lhe pedir para explicar o que é o TFS, as chances são que você iria falar de controle de versão dentro da primeiras algumas frases. Embora o controle de versão desempenham um papel importante dentro TFS, você pode ver em Figura 1 que há muito mais para o TFS. Como com muitos recursos no TFS, o subsistema de controle de versão é acessível por meio do modelo de objeto do TFS. Essa acessibilidade fornece um modelo de extensibilidade que você pode aproveitar dentro de seus próprios processos e ferramentas personalizadas.


Figura 1 recursos do Team Foundation Server

Módulos (assemblies) e Namespaces

Antes de poder acessar a funcionalidade fornecida dentro do modelo de objeto do TFS, você deve primeiramente compreender os namespaces e assemblies necessários. Você vai se lembrar que primeiro artigo usado o namespace Microsoft.TeamFoundation.Client. Este namespace contém as classes e métodos necessários para se conectar a um servidor de configuração do TFS e é localizado dentro do assembly de nome idêntico. Este namespace é central para o desenvolvimento de modelo do objeto TFS de todos.

Ao trabalhar com controle de versão, deve também utilizamos o namespace Microsoft. Este namespace contém as classes necessárias para interagir com o sistema de controle de versão do TFS. Utilizar as APIs dentro desse namespace permite acessar arquivos e pastas, alterações pendentes, mescla, ramos e assim por diante. A classe VersionControlServer dentro desse namespace é a classe principal que fornece acesso ao repositório de controle de versão do TFS.

Um exemplo simples para iniciar

A classe VersionControlServer expõe muitas propriedades, métodos e eventos para interagir com o controle de versão no TFS. Vou começar com um exemplo simples: Recuperando o último ID changeset.

São três etapas básicas necessárias para interagir com a maioria das APIs exposta o modelo de objeto do TFS:

  1. Conecte a um servidor de configuração do TFS.
  2. Obter uma referência para o serviço do TFS que você planeja utilizar.
  3. Fazer uso de várias propriedades, métodos e eventos fornecidos pelo serviço.

Tomando uma abordagem ligeiramente diferente para conectar ao TFS, em oposição aos exemplos apresentados no artigo de agosto, eu vou ligar para TFS usando a classe TeamProjectPicker. A classe TeamProjectPicker exibe uma caixa de diálogo padrão para se conectar a servidores TFS. Esta classe não é apenas útil para aplicativos completo, mas também é muito útil para utilitários simples que você pode precisar alternar entre várias instâncias do TFS.

Criar uma nova instância de TeamProjectPicker e exibi-la usando o método ShowDialog:

 

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

Este código irá exibir uma caixa de diálogo semelhante ao mostrado na Figura 2.


Figura 2 o diálogo de TeamProjectPicker

Clicando em Connect irá retornar uma instância de TfsTeamProject­coleção que representa a coleção selecionada de projeto Team (TPC). Se você preferir usar uma abordagem mais programática (ou seja, sem interação do usuário) para se conectar ao TFS, remeter-se o artigo de agosto para mais exemplos.

Uma vez que você obteve uma referência a um TfsTeamProjectCollection, ele pode ser usado para obter uma instância do serviço VersionControlServer:

 

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

Depois de ter uma referência para o serviço que você pode fazer uso dos métodos expostos pelo serviço:

var latestId = vcs.GetLatestChangesetId();

Este é um exemplo simples, mas que demonstrar as etapas básicas para interagir com o sistema de controle de versão no TFS. No entanto, alguns aplicativos são simples.

"Obtendo o mais recente"

Um cenário comum relacionado ao controle de versão é obter o código-fonte mais recente do repositório — ou seja, "ficando mais recentes." Enquanto trabalhava dentro do Visual Studio, você normalmente obter o código-fonte mais recente clicando um arquivo ou pasta dentro fonte Controlar Explorer (SCE) e selecionando Get Latest Version. Para que isso funcione corretamente, você deve também ter um espaço de trabalho mapeado selecionado. Quando baixar o código-fonte mais recente do servidor, o espaço de trabalho selecionado determina onde ele será armazenado.

Siga estas etapas para obter programaticamente o código-fonte mais recente:

  1. Conecte a um servidor de configuração do TFS.
  2. Obter uma referência para o serviço de controle de versão.
  3. Utilizar um espaço de trabalho existente ou criar um novo espaço de trabalho temporário.
  4. Mapear o espaço de trabalho para uma pasta local.
  5. Baixe os arquivos desejados do espaço de trabalho.

Com base no exemplo anterior, adicione o código mostrado na Figura 3.

Figura 3 Get do último controle de versão

// 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 um espaço de trabalho já existe e você gostaria de usá-lo, substituir linhas 1-4 em Figura 3 com o seguinte:

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

Nota que, se você não souber o nome do espaço de trabalho ou não quer especificá-lo, você pode chamar GetWorkspace (ver anterior exemplo de código), passando apenas um caminho local. Isso retornará o espaço de trabalho mapeado para o caminho local.

Você não precisa mapear o espaço de trabalho por meio de programação, assim você também pode remover linhas 5 e 6.

Identificação de arquivos e pastas para Download

Como você poderia esperar, várias das APIs fornecidos pelo TFS permitem consulta o servidor de controle de versão para itens específicos, como também versões específicas de itens. No exemplo anterior, ao criar uma nova instância de GetRequest, eu tive que fornecer uma instância do ItemSpec. Um ItemSpec, abreviação de item especificação, descreve um conjunto de arquivos ou pastas. Esses itens podem existir no computador local ou no servidor de controle de versão. Neste exemplo específico, eu estou construindo um ItemSpec para retornar todos os arquivos dentro da pasta do servidor "$ / Demo/TFS_VC_API."

O segundo parâmetro no Construtor ItemSpec usado aqui especifica RecursionType, que pode ser nenhum, o cheio ou OneLevel. Este valor determina quantos níveis de profundidade uma API deve considerar ao consultar itens. Especificar um RecursionType de OneLevel irá consultar ou retornar itens de somente o nível mais alto (em relação a ItemSpec). Um valor de inteiro vai consultar ou retornar os itens desde o mais alto nível, bem como a todos os níveis abaixo (novamente, em relação a ItemSpec).

Enquanto um ItemSpec determina quais itens a serem considerados com base no nome e localização, ao consultar o sistema de controle de versão, um VersionSpec, especificação de versão curta, fornece a capacidade de limitar a item de moda baseada na versão. Versão­Spec é uma classe abstrata para que ele não pode ser instanciado diretamente. TFS fornece várias implementações da versão­Spec que você pode fazer uso de, ao consultar o sistema de controle de versão. Figura 4 lista as várias implementações de VersionSpec fornecido fora da caixa com TFS 2012.

Figura 4 tipos de VersionSpec

VersionSpec Description
ChangesetVersionSpec Especifica uma versão com base em um número do changeset.
DateVersionSpec Especifica uma versão com base em um carimbo de data/hora.
LabelVersionSpec Especifica uma versão com base em um rótulo.
LatestVersionSpec Representa a última versão válida no repositório.
WorkspaceVersionSpec Especifica uma versão com base em um nome de espaço de trabalho/proprietário.

Voltando ao exemplo anterior de criar uma GetRequest, especificado VersionSpec.Latest como minha especificação de versão. VersionSpec.Latest é simplesmente uma referência a uma instância de singleton de LatestVersionSpec fornecido apenas por conveniência. Para recuperar o código com base em um rótulo específico, por exemplo, crie uma instância de LabelVersionSpec:

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

Verificar código

Agora que você sabe como identificar e recuperar itens específicos do servidor de controle de versão, vamos olhar como você pode conferir o código-fonte. Em termos TFS, para verificar um item é pend uma edição sobre esse item. Para pend uma editar itens dentro de um espaço de trabalho específico, você chamar o método Workspace.PendEdit. O método PendEdit tem nove de sobrecargas, que exigem um caminho ou uma matriz de caminhos, bem como alguns outros parâmetros opcionais. Dentre os parâmetros opcionais é RecursionType, que funciona exatamente como descrito anteriormente para o ItemSpec.

Por exemplo, para verificar todos os arquivos c# (. cs), fazer esta chamada:

// 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);

Neste exemplo, estou solicitando que TFS pend edita em todos os arquivos c# (via o curinga *.cs) sob a pasta de servidor "$ / Demo/TFS_VC_API." Porque eu estou especificando um RecursionType completo, vou verificar arquivos c# em todas as pastas abaixo o caminho especificado. A assinatura de método específico usada neste exemplo também irá baixar os arquivos de check-out para o caminho local conforme mapeado por espaço de trabalho especificado. Você pode usar uma das versões sobrecarregadas deste método que aceita um argumento do tipo PendChangesOptions e especificar PendChangesOption.Silent para suprimir o download de arquivos quando pendente edições. O valor retornado nos resultados contém uma contagem de itens baixados por causa da chamada para PendEdit.

Edições não são a única ação que você pode pend dentro do sistema de controle de versão. Existem também métodos para pendente:

  • Adiciona-se através de PendAdd
  • Filiais através de PendBranch
  • Exclui-se através de PendDelete
  • Propriedades via PendPropertyName
  • Renomeia via PendRename
  • Undeletes via PendUndelete

Por exemplo, a seguinte código aguarda um novo ramo, chamado Dev, da pasta principal:

// 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);

Abordaremos a ramificação e mesclagem usando as APIs mais detalhadamente em um artigo futuro.

Verificar alterações

Uma vez que você fez alterações para um ou mais arquivos de check-out, você pode vê-los de volta através do método de Workspace.CheckIn. Antes de chamar o método de check-in, no entanto, você deve primeiro obter uma lista de alterações do espaço de trabalho pendentes chamando Workspace.GetPendingChanges. Se você não especificar nenhum parâmetro para o método de GetPendingChanges, você vai voltar todas as alterações pendentes para o espaço de trabalho. Caso contrário, você pode fazer usar de um dos outras 11 sobrecargas e filtrar a lista de pendente alterações retornado pela chamada ao TFS.

O exemplo a seguir irá verificar em todas as alterações pendentes para o espaço de trabalho:

// 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.");

Na primeira linha de código, estou recebendo uma lista de todas as alterações pendentes para o espaço de trabalho. Na segunda linha, confiro tudo de volta para o servidor de controle de versão especificando um comentário a ser associado com o conjunto de alterações. O valor retornado nos resultados contém uma contagem dos itens check-in. Se houver uma ou mais alterações pendentes e resultados volta como zero, então não foram observadas diferenças nos itens pendentes entre o servidor e o cliente.

Pendente edições não são as únicas mudanças check-in para o sistema de controle de versão. Você também verificar:

  • Adições
  • Ramos
  • Exclusões/Undeletes
  • Properties
  • Renomeia

Você também pode desfazer alterações pendentes, chamando o trabalho­espaço.Método de desfazer. Como com o método de check-in, você também deve especificar quais as alterações que você deseja desfazer. O exemplo a seguir irá desfazer todas as alterações pendentes para o espaço de trabalho:

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

Recuperando a história

Uma tarefa comum Team Explorer está exibindo a história de um ou mais arquivos ou pastas. Você pode encontrar a necessidade de fazer isso programaticamente também. Como você poderia esperar, há uma API para consultar o histórico. Na verdade, o método que eu vou discutir está disponível da instância VersionControlServer (conforme representado pela variável vcs nos exemplos anteriores). O método é VersionControlServer.QueryHistory, e tem oito sobrecargas. Este método fornece a capacidade de consultar o servidor de controle de versão de muitas maneiras diferentes, dependendo dos tipos e valores de parâmetros passados para a chamada de método.

Figura 5 mostra que o modo de exibição do histórico para o arquivo Form1. cs pode parecer na SCE.


Figura 5 história para Form1. cs

Você pode replicar essa funcionalidade por meio de programação usando o código mostrado na Figura 6.

Figura 6 recuperar histórico do Item

 

 

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);       }     }   } }

 

Uma atenção especial ao argumento na linha 13, em Figura 6. Eu estou especificando um valor de true para o parâmetro includeChanges. Se você especificar false e, em seguida, alterações específicas para o histórico de versões não sejam incluídas nos resultados retornados e a Figura 6 exemplo não vai exibir os detalhes. Você ainda pode exibir o histórico de alterações básicas sem retornar as alterações, mas alguns detalhes não estará disponível.

Executando o Figura 6 exemplo produz os resultados mostrados na Figura 7.


Figura 7 história da API

Existem muitas outras variações de chamar a API QueryHistory. Para idéias sobre como você pode fazer uso desse método, simplesmente brincar com os recursos de histórico no SCE. Você também pode consultar muito mais do que história. Por exemplo, existem outra métodos relacionados a consulta fornecida pelo VersionControlServer, tais como:

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

Há muita informação disponível a partir do servidor de controle de versão, e os vários métodos de consulta fornecem-lo com uma janela em que a informação.

Próximas Etapas

Os Rangers só começaram a aflorar os recursos de controle de versão expostos o modelo de objeto do TFS. Os recursos abordados neste artigo podem ser útil e poderosa, mas inumeráveis características são expostas pelo servidor de controle de versão do TFS que ainda não abordamos. Alguns exemplos desses recursos incluem ramificação e mesclagem, shelvesets, rótulos e eventos de controle de versão. Com esta série de artigos, esperamos expor muitas dessas APIs e fornecê-lo com o conhecimento que você precisa para utilizar melhor o modelo de objeto do TFS. Fique ligado para mais.

Jeff Bramwell é diretor de arquitetura corporativa na fazenda serviços de crédito da América. Ele tem mais de 20 anos de experiência de desenvolvimento de software e sempre se esforça para seguir o mantra de início simples e trabalhar sua maneira de lá. Seu blog está em devmatter.blogspot.com. Você pode segui-lo no Twitter em twitter.com/jbramwell.

Agradecemos aos seguintes especialistas técnicos pela revisão deste artigo: Brian Blackman, Mike Fourie e Willy-Peter Schaub