Limpeza de Nomes de Arquivos Antes da Migração para SharePoint: Fluxo Prático para Usuários

Ao migrar arquivos para o SharePoint, nomes com caracteres especiais, espaços excessivos ou caminhos longos podem causar erros de sincronização, links quebrados e falhas na pesquisa. O SharePoint e o OneDrive impõem regras de nomenclatura rígidas que diferem dos sistemas de arquivos locais do Windows. Este artigo explica as restrições exatas de nomenclatura no SharePoint e fornece um fluxo de trabalho passo a passo para limpar os nomes dos arquivos antes da migração. Você aprenderá a identificar arquivos problemáticos, renomeá-los em lote e verificar a conformidade para garantir uma migração tranquila.

Por que os Nomes de Arquivos do SharePoint Devem Ser Limpos Antes da Migração

O SharePoint armazena arquivos em um banco de dados de conteúdo SQL Server e os disponibiliza via HTTP. A URL que o SharePoint gera para cada arquivo inclui o caminho do site, o nome da biblioteca, o caminho da pasta e o nome do arquivo. Caracteres válidos em nomes de arquivos do Windows — como o e comercial (&), porcentagem (%) ou cerquilha (#) — são bloqueados ou exigem codificação de URL no SharePoint. Se um nome de arquivo contiver um caractere que o SharePoint não consegue codificar, o upload do arquivo falha ou o arquivo aparece quebrado no navegador.

As regras oficiais de nomenclatura do SharePoint bloqueiam estes caracteres: \ / : ? ” < > | . O til (~) e o sinal de número (#) também são problemáticos em certas posições. Nomes de arquivo não podem começar ou terminar com espaço ou ponto. O caminho completo para um arquivo — URL do site mais biblioteca mais pasta mais nome do arquivo — não deve exceder 400 caracteres. O Windows permite caminhos de até 260 caracteres, então arquivos válidos em uma unidade local podem violar os limites do SharePoint.

Outro problema comum é a presença de espaços ou pontos finais em nomes de pastas. O Windows Explorer oculta espaços finais visualmente, mas o SharePoint os rejeita. Ao copiar uma pasta chamada “Relatórios ” (com espaço no final) para o SharePoint, a pasta falha ao sincronizar ou cria entradas duplicadas.

Lista de Caracteres a Remover ou Substituir

Os seguintes caracteres não são permitidos em nomes de arquivos ou pastas do SharePoint:

• Barra invertida \
• Barra normal /
• Dois-pontos :
• Asterisco
• Ponto de interrogação ?
• Aspas duplas “
• Menor que <
• Maior que >
• Pipe |
• Til ~ (bloqueado no início de um nome de arquivo em algumas versões do SharePoint)
• Cerquilha # (bloqueado no início de um nome de arquivo)
• Porcentagem % (bloqueado no início de um nome de arquivo)
• E comercial & (bloqueado no início de um nome de arquivo)
• Espaço no final
• Ponto no final

Fluxo de Trabalho Passo a Passo para Limpar Nomes de Arquivos

Este fluxo de trabalho pressupõe que você tenha uma cópia local dos arquivos que planeja migrar. Execute estas etapas antes de iniciar a Ferramenta de Migração SharePoint ou arrastar arquivos para uma biblioteca de documentos do SharePoint.

Etapa 1: Verificar a Estrutura de Pastas em Busca de Violações

1. Abra o PowerShell como Administrador
   Pressione a tecla Windows, digite PowerShell, clique com o botão direito em Windows PowerShell e selecione Executar como administrador.
2. Navegue até a pasta raiz da sua origem de migração
   Use o comando cd para mudar para a pasta que contém todos os arquivos e subpastas. Exemplo: cd “C:\Usuários\SeuNome\Documentos\OrigemMigracao”
3. Execute uma verificação para listar todos os arquivos com caracteres ilegais
   Execute este script PowerShell para gerar um arquivo CSV que lista cada arquivo e pasta que viola as regras de nomenclatura do SharePoint:
   Get-ChildItem -Recurse | Where-Object { $_.Name -match '[\\/:\\?"<>\|~#%]' -or $_.Name -match '\s$' -or $_.Name -match '\.$' } | Select-Object FullName, Name | Export-Csv -Path "violacoes.csv" -NoTypeInformation
   Este script verifica todos os caracteres bloqueados, espaços finais e pontos finais. O arquivo CSV aparece no diretório atual do PowerShell.

Etapa 2: Revisar o Relatório de Violações

1. Abra o arquivo violacoes.csv no Excel
   Clique duas vezes no arquivo para abri-lo. Você verá duas colunas: FullName (o caminho completo) e Name (o nome do arquivo ou pasta que contém a violação).
2. Classifique pela coluna Name
   Isso agrupa violações idênticas. Procure por padrões como arquivos com dois-pontos ou arquivos terminando com espaço.
3. Decida uma estratégia de substituição para cada tipo de caractere
   Substitua dois-pontos por hífen, substitua e comercial pela palavra “e” e remova espaços finais completamente. Documente suas regras de substituição para que o script de renomeação seja consistente.

Etapa 3: Executar um Script de Renomeação em Lote

1. Crie um script PowerShell que substitua caracteres ilegais
   Copie o script a seguir em um arquivo de texto e salve como CleanNames.ps1. Ajuste o $sourcePath para corresponder à sua pasta de origem de migração.
   $sourcePath = "C:\Usuários\SeuNome\Documentos\OrigemMigracao"
Get-ChildItem -Path $sourcePath -Recurse -File | ForEach-Object {
$newName = $_.Name -replace '[\\/:\\?"<>\|]', '_'
$newName = $newName -replace '^[~#%]', '_'
$newName = $newName -replace '\s+$', ''
$newName = $newName -replace '\.+$', ''
if ($newName -ne $_.Name) {
Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}
}
Get-ChildItem -Path $sourcePath -Recurse -Directory | ForEach-Object {
$newName = $_.Name -replace '[\\/:\\?"<>\|]', '_'
$newName = $newName -replace '^[~#%]', '_'
$newName = $newName -replace '\s+$', ''
$newName = $newName -replace '\.+$', ''
if ($newName -ne $_.Name) {
Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}
}
   O parâmetro -WhatIf mostra o que seria renomeado sem realmente renomear. Revise a saída.
2. Remova o parâmetro -WhatIf e execute o script novamente
   Após confirmar que as alterações estão corretas, remova -WhatIf de ambas as linhas Rename-Item e execute o script. O script renomeia todos os arquivos e pastas que contêm caracteres ilegais.

Etapa 4: Verificar a Conformidade do Comprimento do Caminho

1. Verifique o comprimento máximo do caminho na sua pasta de origem
   Execute este comando PowerShell para encontrar o caminho completo mais longo:
   Get-ChildItem -Path $sourcePath -Recurse | Where-Object { $_.FullName.Length -gt 400 } | Select-Object FullName, @{Name="Comprimento";Expression={$_.FullName.Length}} | Sort-Object Comprimento -Descending
2. Encurte caminhos que excedam 400 caracteres
   Para cada resultado, renomeie pastas ou arquivos para reduzir o comprimento total do caminho. Uma abordagem comum é encurtar nomes de pastas ou remover aninhamentos desnecessários.

Etapa 5: Executar uma Verificação de Validação Final

1. Repita a verificação da Etapa 1
   Execute o script de verificação novamente. Confirme que o arquivo violacoes.csv está vazio ou contém apenas arquivos que você optou por excluir da migração.
2. Teste um pequeno lote de arquivos no SharePoint
   Faça upload de alguns arquivos limpos para uma biblioteca de documentos de teste. Verifique se você consegue abrir, editar e sincronizar os arquivos sem erros.

Erros Comuns ao Limpar Nomes de Arquivos

Substituir Caracteres Ilegais por Espaço

Um espaço é permitido em nomes de arquivos do SharePoint, mas cria problemas em URLs. O SharePoint codifica espaços como %20, o que torna as URLs longas e difíceis de ler. Substitua caracteres ilegais por um sublinhado ou hífen em vez de espaço.

Esquecer de Limpar Nomes de Pastas

O script PowerShell acima lida tanto com arquivos quanto com pastas. Se você renomear apenas arquivos, nomes de pastas com caracteres ilegais ainda causarão erros de sincronização e navegação quebrada no SharePoint.

Usar a Ferramenta de Migração SharePoint sem Limpeza Prévia

O SPMT pode renomear arquivos durante a migração marcando a opção “Substituir caracteres ilegais.” No entanto, esse recurso renomeia arquivos apenas no nível superior e não corrige nomes de pastas. A limpeza prévia oferece controle total sobre os novos nomes e evita falhas de migração que exigem reiniciar o trabalho.

Ignorar Nomes de Arquivos Duplicados Após Renomeação

Ao substituir caracteres, dois arquivos com nomes semelhantes podem se tornar idênticos. Por exemplo, “Relatório:2024” e “Relatório-2024” ambos se tornam “Relatório_2024” após a renomeação. Antes de executar a renomeação em lote, identifique possíveis duplicatas executando este comando PowerShell:
Get-ChildItem -Path $sourcePath -Recurse -File | Group-Object Name | Where-Object { $_.Count -gt 1 }
Se aparecerem duplicatas, adicione um sufixo como a data ou um número sequencial a um dos arquivos.

Item	Sistema de Arquivos Windows	SharePoint Online
Comprimento máximo do caminho	260 caracteres (260 com suporte a caminho longo)	400 caracteres (URL do site + biblioteca + pasta + nome do arquivo)
Caracteres bloqueados em nomes de arquivo	\ / : ? ” < > |	\ / : ? ” < > | ~ # % no início, espaço no final, ponto no final
Espaço no final permitido	Sim (oculto no Explorer)	Não
Ponto no final permitido	Sim	Não
Diferenciação entre maiúsculas e minúsculas	Não diferencia, mas preserva maiúsculas/minúsculas	Não diferencia, mas preserva maiúsculas/minúsculas
Codificação de URL necessária	Não	Sim, para caracteres como & e #

Depois de limpar todos os nomes de arquivos, execute a Ferramenta de Migração SharePoint com a opção de validação ativada. Isso confirma que cada arquivo atende às regras de nomenclatura do SharePoint antes do upload real começar. Se a ferramenta relatar violações restantes, corrija-as na pasta de origem e execute novamente a validação.

Para migrações grandes com milhares de arquivos, agende o script de limpeza para ser executado como uma tarefa agendada na noite anterior à migração. Teste o script em um subconjunto de arquivos primeiro para verificar se as regras de substituição produzem nomes legíveis. Mantenha um registro de todos os arquivos renomeados para que você possa mapear nomes antigos para novos nomes se os usuários precisarem localizar documentos específicos após a migração.