safe (Referência de C#)

A safe palavra-chave contextual marca uma declaração como não exigindo um unsafe contexto em seu site de uso no modelo de segurança de memória atualizado. O safe modificador é o equivalente a unsafe. Um contexto não seguro não é necessário para os chamadores de uma safe declaração, enquanto unsafe propaga a obrigação de auditar a segurança para o chamador.

Usar a safe palavra-chave em si requer a opção do AllowUnsafeBlocks compilador (-unsafe), mesmo que os chamadores não precisem de um unsafe contexto. As declarações comuns são seguras por padrão, portanto, omita safe onde não é necessário evitar a necessidade de compilação não segura desnecessariamente.

Importante

A safe palavra-chave faz parte do modelo de segurança de memória atualizado, um recurso de visualização em C# 15 e .NET 11. Defina LangVersion para preview habilitar a sintaxe. Para também impor as regras atualizadas, incluindo opções ou unsafe opções explícitas safe e obrigações de chamador não seguras, habilite o recurso do updated-memory-safety-rules compilador. Para obter detalhes de ativação, consulte Habilitar as regras de segurança de memória atualizadas. Para obter o design completo, consulte a especificação do recurso de segurança de memória.

Declarações permitidas e necessárias

Você pode aplicar safe a declarações que permitem um modificador não seguro, incluindo métodos, construtores, propriedades e campos. Para declarações comuns, o modificador pode tornar o contrato pretendido explícito, inclusive no código gerado pelo código-fonte. Ele não se limita a extern membros e campos de layout.

Determinadas declarações exigem uma escolha explícita de safe ou unsafe quando as regras atualizadas estão habilitadas. As seções a seguir descrevem extern membros e campos de layout explícitos ou estendidos.

Ao contrário unsafede , safe não estabelece um contexto léxico. Ele não torna as operações não seguras em um corpo membro seguras ou cancela um contexto não seguro delimitando. Você não pode combinar os modificadores e unsafe modificadores safe na mesma declaração; isso produz CS9388.

Em compiladores mais recentes, safe as declarações também exigem AllowUnsafeBlocks, mesmo que os chamadores não precisem de um contexto não seguro. Defina <AllowUnsafeBlocks>true</AllowUnsafeBlocks> no arquivo de projeto para resolver o CS9401. Essa verificação do modificador é independente da aceitação de imposição de regras atualizadas. Roslyn documenta como introduzido no Visual Studio 2026 versão 18.13, após .NET 11.0.100; o compilador 11 RC2 do .NET não impõe esse requisito para safe. Para o limite do compilador e a distinção de CS0227 em blocos não seguros, consulte os requisitos de contexto não seguros.

Membros extern

Um extern membro chama o código nativo para que o compilador não possa classificar sua segurança. No modelo atualizado, você marca todas as extern declarações, incluindo um LibraryImport método parcial, safe ou unsafe:

// Syntax requires LangVersion preview; enforcement requires the updated-memory-safety-rules compiler feature.
[LibraryImport("libc")]
internal static safe partial int getpid();

[LibraryImport("libc", StringMarshalling = StringMarshalling.Utf8)]
internal static unsafe partial nint strlen(byte* str);

getpid não usa parâmetros e retorna um primitivo, portanto, o autor atesta que a chamada é segura e os chamadores a usam sem contexto unsafe . strlen usa um ponteiro bruto que o código nativo desreferencia, portanto, a declaração é unsafe e propaga a obrigação para seus chamadores. Com as regras atualizadas habilitadas, omitir ambos os modificadores é um erro.

Campos de layout explícitos ou estendidos

Em um tipo com [StructLayout(LayoutKind.Explicit)] ou [ExtendedLayout], o compilador não pode classificar a segurança de cada campo de instância por conta própria. Você marca cada campo desse tipo safe ou unsafe:

// Syntax requires LangVersion preview; enforcement requires the updated-memory-safety-rules compiler feature.
[StructLayout(LayoutKind.Explicit)]
internal struct Union
{
    [FieldOffset(0)]
    internal safe int AsInt;

    [FieldOffset(0)]
    internal safe float AsFloat;
}

Um campo que contém um ponteiro nativo ou cujo tipo de outra forma carrega um invariável que o sistema de tipos não pode expressar é unsafe. Um campo cujo tipo é totalmente descrito pelo sistema de tipos é safe. A mesma regra se aplica a campos de layout explícito e campos de layout estendido. Assim como acontece com extern os membros, omitir ambos os modificadores é um erro quando as regras atualizadas estão habilitadas.

Aplique os mesmos modificadores a campos de instância em tipos com não zero StructLayoutAttribute.Pack ou StructLayoutAttribute.Size, incluindo layout sequencial e automático. Por exemplo, um tipo de layout sequencial com Pack = 1 requer a mesma escolha explícita. Valores não especificados ou zero não disparam a regra adicional sozinhos. Campos estáticos e constantes são isentos. Para campos de backup sintetizados, coloque o modificador na propriedade ou evento proprietário.

Para obter a mensagem CS9392 e correções para outro armazenamento sintetizado, consulte a segurança do layout de campo.

Especificação da linguagem C#

Para obter mais informações, consulte código não seguro na Especificação da Linguagem C#. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso de C#.

Para o design do modelo de segurança de memória atualizado, consulte a especificação do recurso de segurança de memória.

Consulte também

  • Última atualização em