기존 Windows Admin Center 확장을 Angular 11로 업그레이드

Windows Admin Center가 Angular 11.0으로 업그레이드됩니다! 이 업그레이드는 최신 기능, 보안 및 성능을 제공합니다. 이 기능을 사용할 수 있게 되어 기쁩니다. 지금까지 Windows Admin Center의 셸이 업그레이드되었습니다. 이제 확장을 업데이트할 차례입니다. 해당 문서의 단계에 따라 확장을 업데이트합니다.

이 프로세스 중 문제가 발생하면 Microsoft 연락처에 문의하세요. 요청을 라우팅하는 데 도움이 됩니다.

예비 단계

Angular 11로 업그레이드를 시작하기 전, 최신 Windows Admin Center 셸 및 개발 도구를 사용하여 개발자 환경을 구성해야 합니다. 업그레이드 프로세스를 진행하기 전에 다음 단계를 완료하세요.

1. 업그레이드된 셸로 개발 모드(msiexec /i WindowsAdminCenter<version>.msi DEV_MODE=1)에서 최신 버전의 Windows Admin Center를 설치합니다. 이 항목이 제공되지 않은 경우 Microsoft 연락처에 문의하세요.
2. (권장) 리포지토리에 분기를 features/ng11 생성합니다.
3. (권장)version.json 버전을 (N+1).0.0로 업데이트합니다.
4. PowerShell 콘솔에서 Angular 버전의 해당 노드 버전으로 전환해야 합니다(자세한 내용은 셸의 두 분기 작업을 참조). Angular 11의 경우 nvm use 12.18.3을 실행합니다. 이 변경 내용이 적용되도록 터미널을 닫습니다.
5. npm 충돌을 방지하려면 node_modules 폴더를 정리합니다.

자동화된 업그레이드 프로세스

다음 단계를 진행하기 전에 아직 실행하지 않은 경우 npm install -g @microsoft/windows-admin-center-sdk@experimental을 실행하여 Windows Admin Center CLI 도구를 다운로드하고 설치합니다.

1. 리포지토리의 루트 수준에서 wac upgrade --audit=false --experimental을 실행합니다.

   • 다른 확장에서 사용하는 확장 리포지토리에서 작업하는 경우 --library 플래그도 포함합니다.

   라이브러리 플래그를 사용한 경우 src/package.json의 name 속성을 확장에 고유한 것으로 편집하세요.

2. (조건부) 확장 리포지토리에 다른 확장 패키지에 대한 종속성이 있는 경우 해당 확장에 대한 새 각 버전을 수동으로 선택해야 합니다(예: msft-sme-certificate-manager은 msft-sme-event-viewer에 종속성이 있습니다.) 자동화된 도구는 msft-sme-event-viewer 버전을 업데이트하지 않으며 수동으로 업데이트해야 합니다.) 또한 확장에서 가져온 모든 가져오기에 대해 '/dist' 폴더 수준을 지정해야 합니다. 하위 또는 상위 수준 가져오기는 작동하지 않습니다(예: import { foobar } from '@msft-sme/event-viewer'을 import { foobar } from '@msft-sme/event-viewer/dist'로 변경해야 합니다.).

3. app-routing.module.ts을 열고 ./folder-name/file-name#ModuleClass 형식 appRoutes를 () => import('./folder-name/file-name').then(m => m.ModuleClass)으로 변경하세요. 다른 routing.module.ts 파일이 있는 경우 이러한 방식으로 업데이트해야 합니다.

4. UpgradeAudit.txt 파일 제거. 참조에 대해 자동으로 생성되지만 리포지토리로 이동하지 않아도 됩니다.

5. 다음 파일을 살펴보고 @msft-sme의 모든 인스턴스를 다음 @microsoft/windows-admin-center-sdk로 바꿉니다.

• ./angular.json
• ./gulpfile.ts/common/e2e.ts
• ./gulpfile.ts/common/resjson.ts
• ./src/polyfills.ts
• ./src/test.ts

6. 완료한 단계의 결과로 해결되지 않은 오류가 있을 수 있습니다. 빌드 단계를 진행합니다.

빌드 단계

업그레이드 프로세스의 이 시점에서 확장 리포지토리를 빌드할 준비가 되었으며 디버깅 프로세스를 시작할 수 있습니다. 다음 단계를 진행하세요.

1. gulp build를 실행합니다.
2. 린팅 및 컴파일 오류에 주의하세요.
3. 이러한 오류를 수정하고 필요에 따라 1~3단계를 반복하세요.
4. 모든 빌드 오류가 해결되면 변경 내용을 커밋하고 실행 단계를 진행합니다.

빌드 오류를 진단하기 어려운 경우

빌드 단계에서 디버깅하는 동안 발생할 수 있는 일부 오류는 진단하기 어려울 수 있습니다. 다음은 오류를 진단하기 어려운 가장 일반적인 두 가지와 해당 오류를 완화하는 방법입니다.

• NG6002: AppModule의 NgModule.imports에 표시되지만 NgModule 클래스로 확인할 수 없습니다.

  • 이러한 유형의 오류는 일반적으로 업그레이드된 리포지토리가 한 번 이상 성공적으로 빌드되기 전에 빌드 시 발생합니다. 해결하려면 ng serve --prod을 실행합니다. 그런 다음 빌드할 때 이러한 오류가 더 이상 나타나지 않습니다.

• 인터페이스가 다른 인터페이스를 잘못 확장합니다인터페이스를 잘못 보여 주는 그림은 다른 인터페이스 오류를 잘못 확장합니다.

  • 이 오류는 "gulp build"의 inlineCompile 단계에서 발생하며 다운로드한 @types/jasmine 패키지와 @types/jasminewd2 패키지에 필요한 버전이 일치하지 않는 결과로 발생합니다. 이 오류는 @types/jasminewd2 패키지를 제거하여 해결할 수 있습니다.

출력 번들 파일 이름

확장을 빌드할 때 번들의 파일 이름으로 인해 문제가 발생할 수 있습니다. 이러한 문제를 방지하려면 다음 필드에 특히 주의하세요.

• 출력 해시를 사용하도록 설정해야 합니다. 출력 해시를 사용하도록 설정하면 확장의 모든 빌드에 대해 고유한 파일 이름이 생성됩니다. 이 기능을 활성화하지 않는 경우, 중복된 파일 이름으로 인해 브라우저에서 볼 때 확장명 변경 내용을 볼 수 없습니다.
  • 이 필드에서 명령줄을 사용하도록 설정하려면 ng build 명령에 --output-hashing 플래그를 추가 합니다.
  • 리포지토리에서 이 필드를 직접 사용하도록 설정하려면 angular.json 파일로 이동하여 프로덕션 구성에서 outputHashing 필드를 찾습니다.
• 명명된 청크는 사용하지 않도록 설정해야 합니다. 명명된 청크를 사용하도록 설정하면 각 번들 파일에는 원래 모듈 파일 이름이 포함됩니다. 유용해 보일 수 있지만 Windows Admin Center 확장 피드에서 오류가 발생할 수 있는 매우 긴 파일 이름이 발생하는 경우가 많습니다.
  • 이 필드에서 명령줄을 사용하지 않도록 설정하려면 ng build 명령에 --named-chunks 플래그를 추가 합니다.
  • 리포지토리에서 이 필드를 직접 사용하지 않도록 설정하려면 angular.json 파일로 이동하여 프로덕션 구성에서 namedChunks 필드를 찾습니다. 이 필드는 false로 설정합니다.

실행 단계

이제 확장에서 모든 빌드 오류를 해결했으므로 확장을 실행하고 런타임 문제를 해결할 준비가 되었습니다. 확장을 실행하려면 아래 단계를 따릅니다.

1. gulp serve --port <port> --prod --aot을 사용하여 확장을 테스트용으로 로드합니다.
2. 브라우저에서 다음과 같은 확장 관련 런타임 문제를 찾습니다.
   • 확장 페이지가 로드되지 않음
   • 확장 페이지에서 누락된 요소
   • 콘솔 오류
   • 이외에 이상하게 동작하는 다른 모든 것
3. 검색한 런타임 문제를 해결합니다.
4. 확장이 안정화되면 변경 내용을 커밋합니다.

이러한 단계를 마쳤으면 주 분기 만들기를 계속 진행합니다.

주 분기 만들기.

모든 린팅, 컴파일 및 런타임 오류가 해결되면 확장 업그레이드를 완료할 준비가 된 것입니다. 이렇게 하려면 확장 리포지토리에 새 분기를 만들어야 합니다. 다음 단계에 따라 확장 업그레이드를 완료하세요.

1. 업그레이드 프로세스를 완료할 준비가 되었으며 모든 것이 기능 분기 예상대로 작동하는지 확인합니다.
2. 리포지토리에 "main"이라는 새 분기를 만듭니다.
3. 기본으로 병합되는 기능/ng11 분기에서 PR을 만듭니다.
4. 준비가 되면 PR을 완료합니다.
5. 축하합니다. 확장을 성공적으로 업그레이드했습니다.

업그레이드된 확장 릴리스

Windows Admin Center 데스크톱 및 서비스 모드에서 확장을 테스트한 후 업그레이드된 확장의 릴리스를 조정하는 이메일을 wacextensionrequest@microsoft.com로 보냅니다.

셸의 두 분기 작업

Windows Admin Center 셸을 업그레이드하면 환경이 많이 변경되었습니다. 이러한 변경 사항 중 하나는 이전 10.22.0 버전에서 노드 12.18.3을 사용하는 것입니다. 이러한 버전은 호환되지 않으며 각 환경에서 빌드 명령을 실행하기 위해 전역 버전을 전환해야 합니다.

노드 버전을 관리하려면 노드 버전 관리자를 사용하는 것이 좋습니다. https://github.com/coreybutler/nvm-windows

지침에 따라 컴퓨터에 nvm-windows를 설치합니다.

설치되면 다음 명령을 실행하여 환경을 준비할 수 있습니다.

nvm install 12.18.3
nvm use 12.18.3
npm i -g gulp-cli
npm i -g @angular/cli
npm i -g vsts-npm-auth
npm i -g typescript

nvm install 10.22.0
nvm use 10.22.0
npm i -g gulp-cli
npm i -g @angular/cli
npm i -g vsts-npm-auth
npm i -g typescript

그러면 새 버전과 이전 버전의 Angular를 모두 사용하여 개발을 위한 노드 환경이 설정됩니다.

노드 버전 토글

사용 중인 노드 버전은 PowerShell을 사용하여 전환할 수 있습니다.

nvm list 명령을 사용하여 설치된 노드 버전을 나열할 수 있습니다.

nvm use <version> 명령을 사용하여 노드 버전 간에 빠르게 전환할 수 있습니다.

노드, Angular 및 Typescript 버전이 함께 이동하는 전체 인덱스 목록은 노드 - Angular 호환성 인덱스입니다.

참고 항목

이 문서의 모든 버전 번호는 Angular 7에서 Angular 11로의 Windows Admin Center 업그레이드와 관련이 있습니다.

위의 프로세스에 따라 VSTS 인증을 포함한 모든 전역 노드 설정이 손실됩니다.

VSTS 인증을 복원하려면 리포지토리의 루트에서 다음 명령을 실행합니다. vsts-npm-auth -config .npmrc

Angular 11로 확장을 업그레이드할 때 기타 고려해야 할 사항

• 셸의 두 분기로 작업하는 경우 셸 및 확장의 테스트용 로드는 영향을 받지 않습니다.
• copyTarget을 사용하는 경우 어떤 셸 분기에 있는지 알고 있어야 합니다. 작업 중인 확장도 Angular 11로 업그레이드된 경우 2.0 분기에서만 이 명령을 사용하세요.
• 리포지토리가 Angular 11로 업그레이드된 경우 최신 2.x.0 버전의 셸 라이브러리를 사용하세요. 그렇지 않으면 최신 1.x.0 버전을 계속 사용하세요.

package.json 파일을 확인하여 리포지토리가 업그레이드되었는지 확인할 수 있습니다.