Share via

CA1068: CancellationToken 매개 변수가 마지막으로 와야 합니다.

  • 아티클
속성 값
규칙 ID CA1068
타이틀 CancellationToken 매개 변수는 마지막에 위치해야 합니다.
범주 디자인
수정 사항이 주요 변경인지 여부 주요 변경
.NET 8에서 기본적으로 사용 제안 사항

원인

메서드에 마지막 매개 변수가 아닌 CancellationToken 매개 변수가 있습니다.

기본적으로 이 규칙은 전체 코드베이스를 분석하지만 이는 구성 가능합니다.

규칙 설명

장기 실행 작업 또는 비동기 작업을 수행하는 취소 가능한 메서드는 일반적으로 취소 토큰 매개 변수를 사용합니다. 각 취소 토큰에는 토큰을 만들고 취소할 수 있는 계산에 사용하는 CancellationTokenSource가 있습니다. 호출자에서 호출 수신자에 취소 토큰을 전달하는 메서드 호출의 긴 체인을 포함하는 것이 일반적입니다. 따라서 취소할 수 있는 계산에 참여하는 많은 메서드가 취소 토큰 매개 변수를 사용합니다. 그러나 취소 토큰 자체는 일반적으로 대부분의 해당 메서드의 핵심 기능과 관련이 없습니다. 이러한 매개 변수를 목록의 마지막 매개 변수로 포함하는 것이 바람직한 API 디자인 관행으로 여겨집니다.

특별 케이스

규칙 CA1068은 다음과 같은 특별한 경우에 발생하지 않습니다.

  • 메서드에 비선택적인 취소 토큰 매개 변수 다음에 하나 이상의 선택적 매개 변수(Visual Basic 선택 사항)가 있습니다. 컴파일러에서는 선택적 매개 변수가 아닌 모든 매개 변수 뒤에 모든 선택적 매개 변수가 정의되어 있어야 합니다.
  • 메서드에 취소 토큰 매개 변수 다음에 하나 이상의 ref 또는 out 매개 변수(Visual Basic에서 ByRef)가 있습니다. ref 또는 out 매개 변수는 메서드의 출력값을 나타내기 때문에 목록의 끝에 포함하는 것이 일반적입니다.

위반 문제를 해결하는 방법

메서드 시그니처를 변경하여 취소 토큰 매개 변수를 목록의 끝으로 이동합니다. 예를 들어 다음 두 코드 조각은 규칙의 위반과 위반을 해결하는 방법을 보여 줍니다.

// Violates CA1068
public void LongRunningOperation(CancellationToken token, string usefulParameter)
{
    ...
}

// Does not violate CA1068
public void LongRunningOperation(string usefulParameter, CancellationToken token)
{
    ...
}

경고를 표시하지 않는 경우

메서드가 이미 제공된 라이브러리에 속한 외부에 표시되는 퍼블릭 API인 경우 라이브러리 소비자의 호환성이 손상되는 변경을 방지하기 위해 해당 규칙에서 경고를 표시하지 않는 것이 안전합니다.

경고 표시 안 함

단일 위반만 표시하지 않으려면 원본 파일에 전처리기 지시문을 추가하여 규칙을 사용하지 않도록 설정한 후 다시 사용하도록 설정합니다.

#pragma warning disable CA1068
// The code that's violating the rule is on this line.
#pragma warning restore CA1068

파일, 폴더 또는 프로젝트에 대한 규칙을 사용하지 않도록 설정하려면 구성 파일에서 심각도를 none으로 설정합니다.

[*.{cs,vb}]
dotnet_diagnostic.CA1068.severity = none

자세한 내용은 방법: 코드 분석 경고 표시 안 함을 참조하세요.

분석할 코드 구성

다음 옵션을 사용하여 이 규칙이 실행될 코드베이스 부분을 구성합니다.

이 규칙, 적용되는 모든 규칙 또는 적용되는 이 범주(디자인)의 모든 규칙에 대해 이러한 옵션을 구성할 수 있습니다. 자세한 내용은 코드 품질 규칙 구성 옵션을 참조하세요.

특정 API 화면 포함

접근성을 기반으로 이 규칙을 실행할 코드베이스의 파트를 구성할 수 있습니다. 예를 들어 규칙이 퍼블릭이 아닌 API 표면에서만 실행되도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.api_surface = private, internal

특정 기호 제외

분석에서 형식 및 메서드와 같은 특정 기호를 제외할 수 있습니다. 예를 들어 MyType이라는 형식 내 코드에서 규칙을 실행하지 않도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

옵션 값의 허용되는 기호 이름 형식(|로 구분):

  • 기호 이름만(포함하는 형식 또는 네임스페이스와 관계없이 해당 이름의 모든 기호 포함).
  • 기호의 설명서 ID 형식에 있는 정규화된 이름. 각 기호 이름에는 메서드의 경우 M:, 형식의 경우 T:, 네임스페이스의 경우 N:과 같은 기호 종류 접두사가 필요합니다.
  • 생성자의 경우 .ctor이고 정적 생성자의 경우 .cctor입니다.

예:

옵션 값 요약
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType MyType이라는 모든 기호와 일치합니다.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 MyType1 또는 MyType2라는 모든 기호와 일치합니다.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) 특정 메서드 MyMethod를 지정된 정규화된 시그니처와 비교합니다.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) 특정 메서드 MyMethod1 및 MyMethod2를 개별 정규화된 시그니처와 비교합니다.

특정 형식 및 해당 파생 형식 제외

분석에서 특정 형식과 해당 파생 형식을 제외할 수 있습니다. 예를 들어 MyType이라는 형식 및 해당 파생 형식 내에 있는 메서드에서 규칙이 실행되지 않도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

옵션 값의 허용되는 기호 이름 형식(|로 구분):

  • 형식 이름만(포함하는 형식이나 네임스페이스와 관계없이 해당 이름의 모든 형식 포함)
  • 기호의 설명서 ID 형식에 있는 정규화된 이름(선택적 T: 접두사 포함)

예:

옵션 값 요약
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType MyType이라는 모든 형식 및 모든 해당 파생 형식과 일치합니다.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 MyType1 또는 MyType2라는 모든 형식 및 모든 해당 파생 형식과 일치합니다.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType 지정된 정규화된 이름의 특정 MyType 형식 및 모든 해당 파생 형식과 일치합니다.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 개별 정규화된 이름의 특정 MyType1, MyType2 형식 및 모든 해당 파생 형식과 일치합니다.

참고 항목