A origem do Dynamo está hospedada no Github para que qualquer pessoa possa clonar e fazer contribuições. Neste capítulo, analisaremos como clonar o repositório usando o git, compilar os arquivos de origem com o Visual Studio, executar e depurar uma compilação local e extrair as novas alterações do Github.

Localizar os repositórios do Dynamo no Github

O Github é um serviço de hospedagem baseado no git, um sistema de controle de versão para rastrear alterações e coordenar o trabalho entre as pessoas. O Git é uma ferramenta que podemos aproveitar para fazer download dos arquivos de origem do Dynamo e mantê-los atualizados com alguns comandos. O uso desse método evitará o trabalho desnecessário e inerentemente confuso de fazer o download e substituir manualmente os arquivos de origem em cada atualização. O sistema de controle de versão git rastreará as diferenças entre um repositório de código local e remoto.

A origem do Dynamo está hospedada no DynamoDS Github neste repositório: https://github.com/DynamoDS/Dynamo

Arquivos de origem do Dynamo.

1. Clonar ou fazer o download de todo o repositório

2. Visualizar outros repositórios do DynamoDS

3. Arquivos de origem do Dynamo

4. Arquivos específicos do Git

Extrair o repositório do Dynamo usando o git

Antes de clonar o repositório, precisamos instalar o git. Siga este guia curto para obter as etapas de instalação e como configurar um nome de usuário e e-mail do github. Neste exemplo, usaremos o git na linha de comando. Esse guia presume que você esteja usando o Windows, mas também é possível usar o git no Mac ou Linux para clonar a origem do Dynamo.

Precisamos de uma URL para o repositório do Dynamo para clonar. Essa URL pode ser encontrada no botão “Clonar ou fazer o download” na página do repositório. Copie a URL para colar no prompt de comando.

1. Selecionar “Clonar ou fazer o download”

2. Copiar a URL

Com o git instalado, podemos clonar o repositório do Dynamo. Comece abrindo o prompt de comando. Em seguida, use o comando de alteração de diretório cd para navegar até a pasta na qual desejamos que os arquivos de origem sejam clonados. Neste caso, criamos uma pasta chamada Github em Documents.

cd C:\Users\username\Documents\GitHub

Substitua “username” por seu nome de usuário

Na próxima etapa, executaremos um comando git para clonar o repositório do Dynamo para o local que especificamos. A URL no comando é obtida clicando no botão “Clonar ou fazer o download” no Github. Execute esse comando no terminal de comando. Observe que isso clonará a ramificação mestre de repositório do Dynamo, que é o código mais atualizado do Dynamo, e conterá a versão mais recente do código do Dynamo. Essa ramificação muda diariamente.

git clone https://github.com/DynamoDS/Dynamo.git

Saberemos que o git está funcionando se a operação de clonagem tiver sido concluída com êxito. No gerenciador de arquivos, navegue até o diretório onde você clonou para ver os arquivos de origem. A estrutura de diretórios deve ser idêntica à ramificação mestre do repositório do Dynamo no Github.

1. Arquivos de origem do Dynamo

2. Arquivos do Git

Compilar o repositório usando o Visual Studio

Com os arquivos de origem agora clonados em nosso computador local, podemos compilar um arquivo executável para o Dynamo. Para fazer isso, precisamos configurar o Visual Studio IDE e assegurar que o .NET Framework e o DirectX estejam instalados.

• Faça o download e instale o Microsoft Visual Studio Community 2015, um IDE gratuito e completo (ambiente de desenvolvimento integrado – as versões posteriores também podem funcionar)

• Faça o download e instale o Microsoft .NET Framework 4.5 ou posterior

• Instale o Microsoft DirectX do repositório local do Dynamo (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe)

O .NET e o DirectX podem já estar instalados.

Quando tudo estiver pronto, podemos iniciar o Visual Studio e abrir a solução Dynamo.All.sln localizada em Dynamo\src.

1. Selecionar File > Open > Project/Solution

2. Navegar até o repositório do Dynamo e abrir a pasta src

3. Selecionar o arquivo da solução Dynamo.All.sln

4. Selecionar Open

Antes de podermos compilar a solução, algumas configurações devem ser especificadas. Primeiro, devemos compilar uma versão de depuração do Dynamo para que o Visual Studio possa coletar mais informações durante a depuração para nos ajudar a desenvolver, e queremos a AnyCPU como destino.

Elas se tornarão pastas dentro da pasta bin

1. Para este exemplo, escolhemos Debug como a Configuração da solução

2. Definir a Plataforma de soluções como Any CPU

Com o projeto aberto, podemos compilar a solução. Esse processo criará um arquivo DynamoSandbox.exe que podemos executar.

A compilação do projeto restaurará as dependências do NuGet.

1. Selecionar Build > Build Solution.

2. Verificar se a compilação foi bem-sucedida na janela Saída. Deve ser semelhante a ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====

Executar uma compilação local

Se o Dynamo for compilado com êxito, uma pasta bin será criada no repositório do Dynamo com o arquivo DynamoSandbox.exe. No nosso caso, estamos compilando com a opção Depurar, portanto, o arquivo executável estará localizado em bin\AnyCPU\Debug. A execução dessa ação abrirá uma compilação local do Dynamo.

1. O executável do DynamoSandbox que acabamos de criar. Execute isso para iniciar o Dynamo.

Agora estamos quase totalmente preparados para começar a desenvolver o Dynamo.

Para obter instruções sobre como compilar o Dynamo para outras plataformas (por exemplo, Linux ou OS X), visite esta página wiki.

Depurar uma compilação local usando o Visual Studio

A depuração é um processo de identificação, isolamento e correção de um problema ou bug. Após o Dynamo ter sido criado com êxito da origem, poderemos usar diversas ferramentas no Visual Studio para depurar um aplicativo em execução, por exemplo, o complemento DynamoRevit. Podemos analisar seu código-fonte para localizar a causa de um problema ou observar o código em execução no momento. Para obter uma explicação mais detalhada de como depurar e navegar no código no Visual Studio, consulte o Documentos do Visual Studio.

Para o aplicativo independente do Dynamo, DynamoSandbox, abordaremos duas opções para depuração:

• Compilar e iniciar o Dynamo diretamente no Visual Studio

• Anexar o Visual Studio a um processo em execução do Dynamo

Iniciar o Dynamo no Visual Studio recompila a solução para cada sessão de depuração, se necessário; portanto, se fizermos alterações na origem, elas serão incorporadas ao depurar. Com a solução Dynamo.All.sln ainda aberta, selecione Debug, AnyCPU e DynamoSandbox nos menus suspensos e clique em Start. Isso compilará o Dynamo, iniciará um novo processo (DynamoSandbox.exe) e anexará o depurador do Visual Studio a ele.

Compilar e iniciar o aplicativo diretamente no Visual Studio

1. Definir a configuração como Debug

2. Definir a plataforma como Any CPU

3. Definir o projeto de inicialização como DynamoSandbox

4. Clicar em Start para iniciar o processo de depuração

Como alternativa, podemos desejar depurar um processo do Dynamo que já está em execução para solucionar um problema com um gráfico ou pacote específico aberto. Para essa finalidade, abriríamos os arquivos de origem do projeto no Visual Studio e anexaríamos a um processo do Dynamo em execução usando o item de menu de depuração Attach to Process.

Anexar um processo em execução ao Visual Studio

1. Selecionar Debug > Attach to Process...

2. Escolher DynamoSandbox.exe

3. Selecionar Attach

Em ambas as situações, estamos anexando o depurador a um processo que desejamos depurar. Podemos definir pontos de quebra no código antes ou após iniciar o depurador que fará com que o processo pause imediatamente antes de executar essa linha de código. Se uma exceção não capturada for gerada durante a depuração, o Visual Studio pulará para onde ela ocorreu no código-fonte. Esse é um método eficiente para localizar falhas simples e exceções não tratadas e também para entender o fluxo de execução de um aplicativo.

Durante a depuração do DynamoSandbox, definimos um ponto de quebra no construtor do nó Color.ByARGB que faz com que o processo do Dynamo pause quando o nó é instanciado. Se esse nó estava gerando uma exceção ou causando um erro fatal no Dynamo, poderíamos passar por cada linha no construtor para descobrir onde o problema estava ocorrendo.

1. O ponto de quebra

2. A pilha de chamadas mostrando a função que está sendo executada no momento e as chamadas de função anteriores.

Na próxima seção, Compilar o DynamoRevit da origem, analisaremos um exemplo específico de depuração e explicaremos como definir pontos de quebra, passar pelo código e ler a pilha de chamadas.

Extrair a compilação mais recente

Como a origem do Dynamo está hospedada no Github, a maneira mais fácil de manter os arquivos de origem locais atualizados é extraindo as alterações usando os comandos git.

Usando a linha de comando, defina o diretório atual para o repositório do Dynamo:

cd C:\Users\username\Documents\GitHub\Dynamo

Substitua "username" por seu nome de usuário

Use o seguinte comando para extrair as alterações mais recentes:

git pull origin master

1. Aqui podemos ver que o repositório local foi atualizado com as alterações do remoto.

Além de extrair as atualizações, há mais quatro fluxos de trabalho git com os quais se familiarizar.

• Bifurcar o repositório do Dynamo para criar uma cópia separada do original. Todas as alterações feitas aqui não afetarão o repositório original e as atualizações poderão ser buscadas ou enviadas com solicitações de extração. A bifurcação não é um comando git, mas é um fluxo de trabalho que o github adiciona – o modelo de solicitação de extração bifurcado é um dos fluxos de trabalho mais comuns para contribuir para projetos de código-fonte aberto on-line. Vale a pena aprender se você deseja contribuir no Dynamo.

• Ramificação – trabalhar em experimentos ou em novas operações isolados de outros trabalhos em ramificações. Isso facilita o envio de solicitações de extração.

• Fazer confirmações com frequência, após completar uma unidade de trabalho e após uma alteração que possa desejar ser desfeita. Os registros de confirmações mudam para o repositório e serão visíveis ao fazer uma solicitação de extração para o repositório principal do Dynamo.

• Criar solicitações de extração quando as alterações estiverem prontas para serem oficialmente propostas para o repositório principal do Dynamo.

A equipe do Dynamo tem instruções específicas sobre a criação de solicitações de extração. Consulte a seção Solicitações de extração nesta documentação para obter itens mais detalhados a serem tratados.

Consulte esta página da documentação para obter uma lista de referência de comandos git.

Os arquivos de origem do DynamoRevit também estão hospedados no DynamoDS Github para que os desenvolvedores façam contribuições e compilem versões beta. A compilação do DynamoRevit da origem geralmente segue o mesmo processo que o Dynamo, com exceção de alguns detalhes importantes:

• O DynamoRevit faz referência a montagens do Dynamo, portanto, elas devem ser compiladas com pacotes NuGet correspondentes. Por exemplo, o DynamoRevit 2.x não será carregado no Dynamo 1.3.

• O DynamoRevit é específico para as versões do Revit, por exemplo: a ramificação do DynamoRevit 2018 deve ser executada no Revit 2018.

Para este guia, usaremos o seguinte:

• Revit 2023

• A compilação mais recente do DynamoRevit compilada na ramificação Revit2023

• A compilação mais recente do Dynamo

Para garantir uma compilação bem-sucedida, clonaremos e compilaremos os repositórios do Dynamo e do DynamoRevit para usar nesta apresentação.

Observação: A compilação manual do Dynamo antes do DynamoRevit só será necessária se você estiver compilando o Dynamo 1.x e o DynamoRevit 1.x – as versões mais recentes do repositório do DynamoRevit dependem do gerenciador de pacotes do NuGet para as dependências do Dynamo necessárias para a compilação. Embora uma compilação do DynamoRevit 2.x não exija a extração manual do Dynamo, você ainda precisará dos dlls principais em outro lugar para realmente executar o addin do DynamoRevit. Portanto, vale a pena extrair e compilar o Dynamo. Veja mais abaixo:

Localização do repositório do DynamoRevit no Github

O código do projeto DynamoRevit reside em um repositório separado no Github do código-fonte do Dynamo principal. Esse repositório contém os arquivos de origem para nós específicos do Revit e o complemento do Revit que carrega o Dynamo. As compilações do DynamoRevit para diferentes versões do Revit (2016, 2017 ou 2018, por exemplo) são organizadas como ramificações no repositório.

A origem do DynamoRevit está hospedada aqui:

1. Clonar ou fazer download do repositório

2. As ramificações do DynamoRevit fazem referência a versões do Revit

Clonar o repositório usando o git

Em um processo semelhante ao da extração do repositório do Dynamo, usaremos o comando git clone para clonar o DynamoRevit e especificaremos a ramificação que corresponde à nossa versão do Revit. Para começar, abriremos uma interface de linha de comando e definiremos o diretório atual para o local onde desejamos clonar os arquivos.

cd C:\Users\username\Documents\GitHub altera o diretório atual

Substitua username por seu nome de usuário

Agora podemos clonar o repositório para esse diretório. Embora precisemos especificar uma ramificação do repositório, podemos alternar para essa ramificação após a clonagem.

git clone https://github.com/DynamoDS/DynamoRevit.git clona o repositório de um URL remoto e, por padrão, alterna para a ramificação mestre.

Quando o repositório tiver terminado a clonagem, altere o diretório atual para a pasta do repositório e alterne para a ramificação que corresponde à versão instalada do Revit. Neste exemplo, estamos usando o Revit RC2.13.1_Revit2023. Todas as ramificações remotas podem ser visualizadas na página do Github no menu suspenso Ramificações.

cd C:\Users\username\Documents\GitHub\DynamoRevit altera o diretório para DynamoRevit. git checkout RC2.13.1_Revit2023 define a ramificação atual como RC2.13.1_Revit2023. git branch verifica em qual ramificação estamos e mostra as outras que existem localmente.

A ramificação com um asterisco é a que está atualmente verificada. A ramificação Revit2018 é exibida porque já foi verificada anteriormente e, portanto, ela existe localmente.

É importante escolher a ramificação correta do repositório para assegurar que, quando o projeto for compilado no Visual Studio, ele fará referência a montagens na versão correta do diretório de instalação do Revit, especificamente RevitAPI.dll e RevitAPIUI.dll.

Compilar o repositório usando o Visual Studio

1. Clicar com o botão direito do mouse em restorepackages.bat e selecione Run as administrator

Se os pacotes forem restaurados com êxito, uma pasta packages será adicionada à pasta src com os pacotes beta NuGet mais recentes.

1. Os pacotes beta mais recentes do Dynamo NuGet

Com os pacotes restaurados, abra o arquivo de solução DynamoRevit.All.sln do Visual Studio em src e compile a solução. A compilação pode ter problemas para encontrar AssemblySharedInfo.cs inicialmente. Se isso acontecer, a nova execução da compilação resolverá esse problema.

1. Selecionar Build > Build Solution

2. Verificar se a compilação foi bem-sucedida na janela Saída. A mensagem deve ser ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====.

Executar uma compilação local do DynamoRevit no Revit

Crie um arquivo Dynamo.addin na pasta de complementos do Revit localizada em C:\ProgramData\Autodesk\Revit\Addins\2023. Já tínhamos uma versão do DynamoRevit instalada, portanto, vamos apenas editar o arquivo existente para apontar para a nova compilação.

• Especificar o caminho do arquivo de DynamoRevitDS.dll dentro de <Assembly>...</Assembly>.

Como alternativa, podemos fazer com que o complemento carregue o seletor de versão em vez de uma montagem específica.

• Definir o caminho do arquivo <Assembly>...</Assembly> como DynamoRevitVersionSelector.dll

• <FullClassName>...</FullClassName> especifica a classe a ser instanciada da montagem que apontamos com o caminho do elemento de montagem acima. Essa classe será o ponto de entrada de nosso complemento.

Além disso, precisamos remover o Dynamo existente que é fornecido com o Revit. Para fazer isso, vá para C:\\Program Files\Autodesk\Revit 2023\AddIns e remova as duas pastas que contêm o Dynamo – DynamoForRevit e DynamoPlayerForRevit. Será possível excluí-los ou fazer backup deles em uma pasta separada se for necessário recuperar o Dynamo for Revit original.

A segunda etapa é adicionar um caminho de arquivo para as montagens principais do Dynamo ao arquivo Dynamo.config na pasta bin do DynamoRevit. O DynamoRevit carregará essas montagens quando o complemento for aberto no Revit. Esse arquivo de configuração permite apontar o complemento do DynamoRevit para diferentes versões do núcleo do Dynamo para desenvolver e testar as alterações no núcleo e no DynamoRevit.

O código deve se parecer com o seguinte:

• Adicionar o caminho do diretório da pasta bin a <add key/>

Clonamos e compilamos o Dynamo logo antes dessa apresentação para garantir que ele funcionará bem com o DynamoRevit. O caminho do diretório aponta para essa compilação.

Agora, quando abrimos o Revit, deverá haver um complemento do Dynamo localizado na guia Gerenciar.

1. Selecionar Manage

2. Clicar no ícone do complemento do Dynamo

3. Uma instância do DynamoRevit

Se uma janela de caixa de diálogo de erro aparecer mostrando montagens ausentes, é provável que tenha havido uma incompatibilidade entre as versões do DynamoCore compiladas e as que estão sendo carregadas no tempo de execução. Por exemplo, o DynamoRevit com os pacotes beta 2.0 mais recentes do DynamoCore não funcionará se você tentar iniciá-lo usando os dlls do Dynamo 1.3. Assegure-se de que ambos os repositórios sejam da mesma versão e que o DynamoRevit esteja extraindo uma versão correspondente das dependências nuget. Essas são definidas no arquivo package.json do repositório do DynamoRevit.

Depurar o DynamoRevit usando o Visual Studio

Na seção anterior, Compilar o Dynamo da origem, apresentamos brevemente a depuração no Visual Studio e como anexar o Visual Studio a um processo. Usando uma exceção no nó Wall.ByCurveAndHeight como exemplo, vamos analisar como anexar a um processo, definir pontos de quebra, passar pelo código e usar a pilha de chamadas para determinar a origem da exceção. Essas ferramentas de depuração geralmente se aplicam aos fluxos de trabalho de desenvolvimento do .net e vale a pena explorá-los fora deste guia.

• Pontos de quebra: estabelecem linhas no código-fonte onde o aplicativo pausará antes da execução. Se um nó estiver causando um erro fatal do DynamoRevit ou retornar um resultado inesperado, poderemos adicionar um ponto de quebra à origem do nó para pausar o processo, entrar no código e inspecionar os valores ao vivo das variáveis até que encontremos a causa do problema

• Passar pelo código explica a origem, linha por linha. Podemos executar funções uma a uma, entrar em uma chamada de função ou sair da função que estamos executando no momento.

• A pilha de chamadas mostra a função que um processo está executando no momento em relação às chamadas de função anteriores que invocaram essa chamada de função. O Visual Studio tem uma janela Pilha de chamadas para exibir isso. Por exemplo, se ocorrer uma exceção fora do código-fonte, poderemos ver o caminho para o código de chamada na pilha de chamadas.

O nó Wall.ByCurveAndHeight gera uma exceção quando recebe uma PolyCurve como sua entrada de curva com a mensagem: “Para BSPlineCurve não implementado”. Com a depuração, podemos descobrir por que exatamente o nó não aceitará esse tipo de geometria como uma entrada para o parâmetro de curva. Neste exemplo, estamos assumindo que o DynamoRevit foi criado com êxito e pode ser executado como um complemento do Revit.

1. O nó Wall.ByCurveAndHeight está gerando uma exceção

Comece abrindo o arquivo de solução DynamoRevit.All.sln, inicie o Revit e inicie o complemento DynamoRevit. Em seguida, anexe o Visual Studio ao processo do Revit com a janela Attach to Process.

O Revit e o Dynamo Revit precisam estar em execução para serem exibidos como um processo disponível

1. Abrir a janela Attach to Process selecionando Debug > Attach to Process...

2. Definir Transport como Default

3. Selecionar Revit.exe

4. Selecionar Attach

Com o Visual Studio anexado ao Revit, abra o código-fonte Wall.ByCurveAndHeight em Wall.cs. Podemos encontrar isso no Gerenciador de soluções em Libraries > RevitNodes > Elements na região Public static constructors do arquivo. Defina um ponto de quebra no construtor do tipo de parede para que quando o nó for executado no Dynamo, o processo seja interrompido e possamos percorrer cada linha de código individualmente. Normalmente, os construtores do tipo sem toque do Dynamo começam com By<parameters>.

1. O arquivo de classe com o construtor para Wall.ByCurveAndHeight

2. Defina um ponto de quebra clicando à esquerda do número da linha ou clicando com o botão direito do mouse na linha de código e selecione Breakpoint > Insert Breakpoint.

Com o ponto de quebra definido, precisamos que o processo seja executado através da função Wall.ByCurveAndHeight. A função pode ser executada novamente no Dynamo reconectando um fio a uma de suas portas, o que forçará o nó a ser executado novamente. O ponto de quebra será atingido no Visual Studio.

1. O ícone do ponto de quebra muda quando é pressionado

2. A janela Pilha de chamadas mostrando o método ativo seguinte

Agora, passe o cursor sobre cada linha no construtor até que a exceção seja atingida. O código realçado em amarelo é a próxima declaração a ser executada.

1. As ferramentas de depuração para navegação no código

2. Pressionar Step Over para executar o código realçado e, em seguida, suspender a execução após a função retornar

3. A próxima instrução a ser executada, indicada pelo realce e pela seta amarelas

Se continuarmos a percorrer a função, veremos a exceção exibida na janela do DynamoRevit. Observando a janela Pilha de chamadas, poderemos ver que a exceção foi originalmente acionada com base em um método chamado Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve. Felizmente, a exceção é tratada aqui, portanto, o Dynamo não teve um erro fatal. O processo de depuração forneceu contexto para o problema, trazendo-nos para outro método no código-fonte.

1. Quando pressionamos a instrução que causa a exceção em Walls.cs, o processo de depuração nos aproxima o mais possível da causa do problema no código do usuário dentro de ProtoToRevitCurve.cs

2. A declaração que causou a exceção em ProtoToRevitCurve.cs

3. Na Pilha de chamadas, podemos ver que a exceção é proveniente do código que não é do usuário

4. Uma janela pop-up que nos fornece informações sobre a exceção

Esse processo pode ser aplicado a qualquer arquivo de origem com o qual estamos trabalhando. Se estivermos desenvolvendo uma biblioteca de nós sem toque para o Dynamo Studio, poderemos abrir a origem da biblioteca e anexar um processo do Dynamo para depurar a biblioteca de nós. Mesmo que tudo funcione perfeitamente, a depuração é uma ótima maneira de explorar o código e descobrir como as coisas estão funcionando.

Extrair a compilação mais recente

Esse processo é quase idêntico à extração de alterações para o Dynamo, exceto que precisaremos garantir que estamos na ramificação correta. Use o comando git branch no repositório do DynamoRevit para ver quais ramificações estão disponíveis localmente e quais estão desmarcadas.

cd C:\Users\username\Documents\GitHub\DynamoRevit define o diretório atual para o repositório do DynamoRevit. git branch verifica se estamos na ramificação correta, RC2.13.1_Revit2023. git pull origin RC2.13.1_Revit2023 extrai as alterações da ramificação RC2.13.1_Revit2023 da origem remota.

A origem simplesmente aponta para a URL original que clonamos.

Temos de ter certeza de qual é a ramificação em que estamos atualmente e qual é a que estamos extraindo para evitar, por exemplo, a extração de alterações de RC2.13.1_Revit2023 para Revit2018.

Conforme mencionado em Compilar o Dynamo da origem, quando estivermos prontos para enviar uma alteração ao repositório do DynamoRevit, poderemos criar uma solicitação de extração seguindo as diretrizes da equipe do Dynamo definidas na seção Solicitações de extração.