Como Usar IronWebScraper com Cursor

Curtis Chau
Curtis Chau
Atualizado: 26 de outubro de 2026

Quando um crawler C# se move de HttpClient e HtmlAgilityPack para IronWebScraper, uma porta que enfileira cada página listada em Init perde registros. IronWebScraper 2026.10.1 pode encerrar tal rastreamento antes de ter solicitado todas as páginas enfileiradas. Em nossos testes, quatro páginas listadas enfileiradas em Init com uma chamada Request cada produziram três, três e duas páginas buscadas em três execuções, e a saída perdeu 10, 10 e 24 de 46 fornecedores sem erro.

Cursor é um editor de código AI construído na base de código do VS Code, com um agente que edita arquivos e executa comandos. Este guia usa duas de suas funcionalidades, os links da documentação que o agente lê e as regras do projeto comprometidas em .cursor/rules, para migrar o crawler do diretório de fornecedores de uma equipe de compras. O crawler copia 46 fornecedores e seus detalhes de contato exclusivos de membros de um diretório comercial para um arquivo CSV, e o guia move-o para IronWebScraper sem alterar uma linha desse arquivo ou exceder o limite de 4 solicitações por segundo do diretório.

O guia segue as funcionalidades de limitação e identidade do tutorial avançado de raspagem web. Cada rastreamento foi executado contra uma cópia local do diretório servida no localhost. Leia os termos de um site público e obtenha permissão antes de escrever um crawler para ele.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronWebScraper

Instale o IronWebScraper executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Com o repositório HarborDirectory aberto, cole esse prompt em um novo chat do Agente.

@src/HarborDirectory/ @README.md

Add a pages command that checks the supplier listing with IronWebScraper.
Invoke it as `dotnet run --project src/HarborDirectory -- pages`.
Stay on IronWebScraper 2026.10.1.

Start with https://ironsoftware.com/webscraper/csharp/llms.txt.
After that, read the advanced tutorial linked from there.

The pages command walks the listing as follows:
- It starts at /directory?page=1 on the test site and follows each Next page link.
- For every listing page, it prints the page number and the number of suppliers on that page.

The directory crawler already loads its key from IRONWEBSCRAPER_LICENSE_KEY in Program.cs.
Don't write the key to any output or file, and don't dump environment variables.

When it builds, run the pages command and show me what it printed.
Text

Não cole a chave de licença em um chat, pois o conteúdo colado pode aparecer em um arquivo de origem, um commit ou um log de build. IronWebScraper 2026.10.1 ignora uma variável de ambiente chamada IRONWEBSCRAPER_LICENSE_KEY, então o Program.cs do repositório copia essa variável para License.LicenseKey. O guia da chave de licença lista os lugares onde a chave pode ser armazenada.



Qual modelo Cursor você deve usar para trabalhar com IronWebScraper?

Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. O teste executado abaixo usou o Composer 2.5.

Como você fornece a documentação do IronWebScraper para o Cursor?

Inclua o link do llms.txt do IronWebScraper na solicitação ou armazene-o em uma regra que toda a equipe compartilha. Em outubro de 2026, o menu @ do Cursor anexa arquivos, pastas, terminais, chats, diferenças do Git e o navegador, então a documentação do IronWebScraper chega ao agente como um link.

O tutorial avançado define RateLimitPerHost em seus exemplos, mas não declara valores padrão, e nenhuma página diz se dois scrapers compartilham um limite de taxa.

@src/HarborDirectory/Legacy/PoliteHttp.cs

Answer these five questions about IronWebScraper without editing any files:
1. Which members replace the 500 ms wait that PoliteHttp keeps between requests?
2. What delay and connection limit per host does a new WebScraper use?
3. When a scraper holds several HttpIdentity objects, which one sends a given request?
4. Can an HttpIdentity send a fixed Authorization header, as PoliteHttp does?
5. Do two scrapers running at once against one host share a rate limit?

Answer only using https://ironsoftware.com/webscraper/csharp/llms.txt, plus the pages linked there.
Cite the source page for each answer.
If the docs don't cover a question, write "not documented" and don't guess.
Text

Como você escreve regras de projeto para o código do crawler IronWebScraper?

Uma regra de projeto é um arquivo .mdc armazenado em .cursor/rules e versionado com o repositório. Cursor ignora um arquivo .md simples nessa pasta, porque um arquivo sem frontmatter não lhe dá uma maneira de decidir quando carregar a regra.

A regra abaixo lista seus padrões de arquivos em globs, separados por vírgulas conforme especificado na página de regras do Cursor, e define alwaysApply como false. O Cursor então o anexa quando um arquivo nesses caminhos está em contexto. Salve como .cursor/rules/harbor-crawlers.mdc.

---
description: IronWebScraper conventions for the Harbor directory crawlers
globs: src/HarborDirectory/**/*.cs, tests/HarborDirectory.Tests/**/*.cs
alwaysApply: false
---

Every scraper in this repository keeps to these rules:
- Fetch and parse pages with IronWebScraper 2026.10.1 only.
- Don't add HttpClient calls or another HTML parser.
- Check IronWebScraper members against https://ironsoftware.com/webscraper/csharp/llms.txt.
- The site at http://localhost:5493 allows 4 requests per second across all scrapers combined.
- Each scraper sets RateLimitPerHost and OpenConnectionLimitPerHost in Init.
- Queue only the first listing page in Init, then follow the Next page link from Parse.
- A login set with NetworkUsername sends each member page twice, once without it and once with it.
- A request that keeps failing never reaches Parse, so check how many records a run wrote.
- When the docs don't list a member, tell me which pages you checked.
Markdown

As regras sobre Init, o login e solicitações falhas registram o comportamento do IronWebScraper que as seções abaixo medem.

Como as chamadas HttpClient e HtmlAgilityPack se mapeiam para o IronWebScraper?

O crawler antigo buscava cada página por si só e esperava entre as solicitações. IronWebScraper enfileira as solicitações, espaça-as por host e chama um método de análise para cada resposta bem-sucedida.

HttpClient e HtmlAgilityPackIronWebScraper
Um loop sobre números de página com GetAsyncRequest para a página 1 em Init, então o link da próxima página enfileirado de Parse
Task.Delay entre solicitaçõesRateLimitPerHost, com OpenConnectionLimitPerHost para solicitações paralelas
DefaultRequestHeaders.UserAgentUserAgent em um HttpIdentity adicionado a Identities
DefaultRequestHeaders.Authorization com credenciais básicasNetworkUsername e NetworkPassword em uma identidade, ou HttpIdentity.DefaultHttpRequestHeaders
Um loop de tentativa que espera por Retry-After em 429 e 503HttpRetryAttempts
SelectNodes e SelectSingleNode com XPathCss ou XPath no Response, que retornam matrizes HtmlNode
File.WriteAllTextAsync para o CSVScrape, que anexa linhas JSON sob WorkingDirectory, ou o próprio escritor do programa

Por que um crawler portado perde páginas listadas?

O guia GitHub Copilot mede como o IronWebScraper descarta solicitações feitas em Init. Nas sondagens para este guia, FailedUrls mantiveram-se em 0 para as páginas perdidas. A sobrecarga de Request que leva uma lista de URLs buscou duas, quatro e três das quatro páginas listadas em três execuções.

Uma solicitação em Init e todas as solicitações subsequentes enfileiradas de um método de análise buscou todos os 46 fornecedores em 8 de 8 execuções, por isso a regra limita Init à página 1 da lista.

Como o IronWebScraper espaça suas solicitações para um host?

Um novo WebScraper usou um RateLimitPerHost de 50 ms, um OpenConnectionLimitPerHost de 2, um MaxHttpConnectionLimit de 10, 8 para HttpRetryAttempts e um HttpTimeOut de 20 segundos. Com esses valores, o crawler enviou as 50 solicitações de diretório com intervalos de 50 a 88 ms.

Contra um site de teste que recusou solicitações chegando muito rapidamente com 429 e um cabeçalho Retry-After, os padrões falharam. Cada URL recusada foi solicitada 9 vezes com o mesmo espaçamento, o cabeçalho Retry-After não fez diferença, e 13 URLs foram abandonadas. O crawler antigo respeitava o Retry-After, então uma porta que depende apenas de tentativas perde registros. Um RateLimitPerHost de 500 ms produziu lacunas de 533 a 563 ms, o que mantém um scraper dentro do limite do diretório.

Como você planeja e executa a migração?

Pressione Shift+Tab na entrada do chat até que o Modo de Planejamento seja selecionado, então envie a solicitação abaixo. Cursor grava o plano como um arquivo Markdown editável.

@src/HarborDirectory/Legacy/ @TestData/expected/suppliers.csv

Plan the move of DirectoryCrawler from HttpClient and HtmlAgilityPack to IronWebScraper.
Leave CertificateScraper out of this change.
Don't write code until I approve the plan.

The plan should answer these questions:
- What replaces the wait, the retry, the user agent and the login in PoliteHttp?
- How does the new scraper reach all four listing pages?
- How does it stay within the request limit in the harbor-crawlers rule?
- How does the suppliers command keep its output file and its column order?

List your assumptions at the end of the plan.
Text

Corrija quaisquer erros no plano. Então construa a partir do plano, ou volte para o Agente e envie essa solicitação.

@harbor-crawlers

The plan is approved. Build it in this order:
1. Run the current suppliers command.
2. Count the rows of out/suppliers.csv that match TestData/expected/suppliers.csv.
3. Replace DirectoryCrawler and PoliteHttp with one IronWebScraper class named SupplierScraper.
4. Remove HtmlAgilityPack from the project file.
5. Build, run the suppliers command again and count the matching rows.

Then tell me both match counts, how long each run took and how many requests the new run sent.
Text

A menção @harbor-crawlers anexa a regra pelo nome.

Qual recurso do Cursor se adapta a cada mudança?

Selecione um recurso com base no escopo da mudança. A guia completa uma edição que o desenvolvedor começou e a edição inline (Ctrl+K) altera uma seleção que uma frase pode descrever. O Agente cobre alterações em vários arquivos ou trabalho que requer um rastreamento, e o Modo Planejamento vale a pena quando uma mudança incorreta custa mais para desfazer do que um plano custa para escrever. Cada solicitação neste guia foi para o Agente ou Modo Planejamento.

Qual identidade envia cada solicitação?

Cada identidade em Identities carrega seu próprio agente de usuário, cookies e login. Sem identidade, o IronWebScraper não enviou nenhum cabeçalho User-Agent. Com várias identidades, escolheu uma aleatoriamente para cada solicitação e para cada tentativa. Um scraper que mantinha uma identidade de membro e uma identidade pública precisou de 140 solicitações para 46 páginas de contato, 94 delas recusadas com 401.

Um login configurado através de NetworkUsername e NetworkPassword custa uma segunda solicitação em cada página protegida. Cada página de membro saiu primeiro sem credenciais, recebeu um 401, e a solicitação credenciada seguiu dentro de 1,4 ms, fora do espaçamento RateLimitPerHost. Passar a identidade do membro para Request remove a escolha aleatória, mas não a segunda solicitação.

O tutorial lista HttpRequestHeaders para cabeçalhos personalizados, mas nenhum cabeçalho colocado lá chegou ao site. A sonda adicionou Authorization e um cabeçalho X-Crawler personalizado, e nenhum dos dois chegou. Um cabeçalho adicionado ao HttpIdentity.DefaultHttpRequestHeaders estático antes de a identidade ser criada foi enviado em cada solicitação e removido a cada 401. Esse dicionário se aplica a cada identidade que o processo cria posteriormente, incluindo páginas públicas.

Como você depura o scraper que já usa o IronWebScraper?

O scraper de certificados já usava o IronWebScraper antes da migração. Ele manteve uma identidade pública e uma identidade de membro, enfileirou as três páginas de registro em Init e não definiu limite de taxa.

@src/HarborDirectory/Scrapers/CertificateScraper.cs

The certificates command should write 32 certificates, but it writes far fewer.
The number it writes also varies between runs.

Find the cause before you change anything:
1. Run the command twice and note both counts.
2. Raise the scraper's LoggingLevel and read what happened to the missing certificates.
3. Explain each cause you find.

Then fix CertificateScraper.
Run the command three times and give me the count from each run.
Text

Saída

O scraper corrigido grava o registro como uma linha JSON por certificado, na ordem como as páginas são analisadas.

As primeiras 10 de 32 linhas de out/certificates.jsonl, um objeto JSON por certificado

As primeiras 10 das 32 linhas em out/certificates.jsonl conforme a execução do teste deixou após o prompt crawl-all, renderizado como texto simples do arquivo.

O que acontece quando dois scrapers rastreiam o mesmo host?

Cada instância WebScraper limita suas próprias solicitações. Dois scrapers que cada um define RateLimitPerHost para 500 ms e usam uma conexão mantiveram duas solicitações em voo e enviaram até 6 solicitações em um segundo para o mesmo host. Sua taxa combinada, portanto, deve ser planejada no código.

@src/HarborDirectory/

Add a crawl-all command that runs SupplierScraper and CertificateScraper at the same time.

The command is done when it meets these conditions:
- It writes the same suppliers.csv and certificates.jsonl as the two separate commands.
- Neither scraper gets a 429.
- It prints each scraper's request count and the total run time.

Run crawl-all, compare both files with TestData/expected and tell me what matched.
Text

Saída

O gráfico conta as solicitações que o site local recebeu em cada segundo da execução crawl-all.

Gráfico de barras empilhadas de solicitações por segundo de SupplierScraper e CertificateScraper, nunca acima do limite de 4

Solicitações por segundo durante a execução crawl-all do teste, extraídas do log de solicitações do site local. 209 solicitações em 100 segundos.

Como você escreve testes de regressão para os scrapers?

Um Response construído com seu construtor público lançou um ArgumentNullException de Css, e o guia ChatGPT Codex explica por que o IronWebScraper só analisa páginas que ele mesmo buscou. Os testes, portanto, servem as páginas salvas por meio de HTTP.

@src/HarborDirectory/ @TestData/pages/

Create an xUnit project at tests/HarborDirectory.Tests and add it to HarborDirectory.slnx.
The tests must not call the Harbor site on port 5493.
Serve the files in TestData/pages from a local listener inside the tests instead.

Write tests for these cases:
- SupplierScraper reads every field from the saved supplier page and contact page.
- CertificateScraper reads every field from the saved certificate page.
- A contact page that answers 401 leaves Email and Phone empty and keeps the supplier.
- A listing page with no Next page link ends the crawl.

Finish by running dotnet test, then report the passing and failing test counts.
Text

O que os prompts produziram em uma execução real?

As compilações do Fresh Release de cada commit que alterou o código repetiram cada rastreamento abaixo contra uma nova cópia do site local. Um script leu o log de solicitações do site e comparou cada arquivo de saída com TestData/expected.

  • Antes da mudança, o crawler HttpClient e HtmlAgilityPack escreveu todos os 46 fornecedores em 96 solicitações e 49,2 segundos.
  • Após a mudança, o SupplierScraper escreveu as mesmas 46 linhas, com o mesmo cabeçalho e ordem de linhas.
  • O novo rastreamento enviou 142 solicitações em 57,9 segundos, e as páginas de contato responderam 46 delas com 401.
  • O Cursor relatou 96 solicitações para a nova execução, uma contagem de solicitações bem-sucedidas apenas.
  • O SupplierScraper enfileirou apenas a primeira página de listagem no Init e seguiu o link da próxima página a partir do Parse.
  • O Cursor respondeu às cinco perguntas de documentação sem alterar um arquivo e não encontrou página que declare os limites padrão ou responda à questão dos dois scrapers.
  • Para o cabeçalho de autorização, o Cursor não encontrou exemplo documentado e descreveu HttpRequestHeaders como enviado com cada solicitação, o que a sonda demonstrou ser incorreto.
  • O plano alegou que fixar a identidade do membro em solicitações de contato evita a busca dupla, o que 46 respostas de 401 refutaram.
  • Antes de sua correção, o comando de certificados escreveu 1 e 0 certificados nas execuções do Cursor e 6 de 32 em uma execução independente.
  • O Cursor acompanhou as falhas até a identidade aleatória, a identidade do membro no pool aleatório e o limite de taxa ausente.
  • O CertificateScraper corrigido ainda solicitou todas as três páginas de registro do Init, contra a regra do projeto.
  • Após a correção, o comando escreveu 32 de 32 certificados em três execuções independentes, cada com 67 solicitações e sem 429.
  • A primeira compilação crawl-all não recebeu 429, e nenhuma segunda segurou mais de 4 solicitações.
  • Duas execuções independentes scroll-all escreveram todos os 46 fornecedores e todos os 32 certificados em 105,2 e 104,8 segundos.
  • Executar os dois comandos um após o outro levou 80,8 segundos.
  • A suíte xUnit passou 4 de 4 testes, e o site na porta 5493 não registrou nenhuma solicitação enquanto eles estavam em execução.
  • Alguns passos foram executados de forma diferente da página. Todos os sete prompts passaram pelo Cursor CLI em uma única sessão sem cabeça. O Modo Plano persistiu após o prompt 03, então os prompts 05 a 07 precisaram da mensagem de acompanhamento "Construa o plano". No prompt 04, o Cursor também alterou o scraper de páginas e o README, o que o prompt não solicitou.

O guia GitHub Copilot limita suas convenções IronWebScraper aos caminhos do crawler e testes em um arquivo de instruções específicas para o caminho, como o arquivo de regras faz aqui. O guia Google Antigravity trabalha a partir do mesmo tutorial avançado e mede o que o cache web do IronWebScraper e o estado de rastreamento salvo mantêm. O registro de execução lista a versão do assistente, modelo, duração e máquina de teste para cada guia.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 150,061Versão:2026.11recém-lançado