GitHub Copilot 사용하여 Windows 위젯 만들기

GitHub Copilot 에이전트 모드 또는 GitHub Copilot CLI를 사용하여 기존 앱 리포지토리에 위젯을 만들 수 있습니다. 이 문서의 재사용 가능한 복사 및 붙여넣기 프롬프트는 에이전트에게 지원되는 위젯 아키텍처를 선택하고, 필요한 원본 및 패키지 등록을 생성하고, 앱을 빌드하고, Windows 위젯 보드에서 위젯의 유효성을 검사하도록 지시합니다. 프롬프트는 별도로 설치할 수 있는 자산으로 제공되지 않고 이 문서에 포함되어 있습니다.

AI 생성 코드는 여전히 검토가 필요합니다. 선택한 API를 Microsoft.Windows.Widgets.Providers API reference와 대조하여 확인하고, 모든 매니페스트 기능 및 패키지 종속성을 검토하며, 프롬프트에 비밀 또는 프로덕션 자격 증명을 포함하지 마세요.

프롬프트를 사용하기 전에

가능한 한 많은 요구 사항을 결정하세요.

• 위젯의 용도, 표시 이름 및 데이터 원본입니다.
• 콘텐츠가 URL에서 Adaptive Card 또는 HTML을 사용해야 하는지 여부입니다.
• 앱이 패키지된 C# 데스크톱 앱, 패키지된 C++/WinRT 데스크톱 앱 또는 PWA인지 여부입니다.
• 지원되는 크기: 소형, 중형 및 대형.
• 사용자 작업, URL 탐색 및 선택적 사용자 지정 설정
• 새로 고침 동작, 오프라인 또는 로그아웃 상태일 때의 대체 콘텐츠 및 위젯별 영구 상태입니다.
• 데스크톱 공급자의 경우 패키지 ID 및 배포하려는 아키텍처를 지정합니다.

선택을 지정하지 않으면 프롬프트는 Copilot이 아키텍처에 영향을 주는 정보를 요청하고 더 작은 구현 세부 정보에는 문서화된 기본값을 사용하도록 지시합니다.

재사용 가능한 위젯 생성 프롬프트

대괄호로 묶인 위젯 요청을 바꾼 다음 전체 프롬프트를 GitHub Copilot 에이전트 모드 또는 대화형 GitHub Copilot CLI 세션에 붙여넣습니다.

Important

프롬프트의 선택적 CLI 배포 경로에서 사용하는 Windows 앱 개발 CLI는 현재 공개 미리 보기로 제공됩니다. 기능 및 명령은 최종 릴리스 전에 변경될 수 있습니다.

Create and validate a Windows widget in this repository.

Widget request:
[Describe the widget's purpose, content, data source, supported sizes, actions,
customization, refresh behavior, preferred language, and packaging constraints.]

Work as an implementation agent, not as an advisor. Inspect the existing repository,
create or update the required files, build the selected architecture, deploy a development
package, and test the widget in the Windows Widgets Board when the local environment supports it.

Never report a build, deployment, or Widgets Board check as passed unless you performed it
and observed the result. If you can't operate or observe the Widgets Board, list each
unperformed check under "Manual verification required" with exact steps and expected results.
Do not infer a pass from successful compilation, package registration, or Designer rendering.

Use these requirements:

1. Select exactly one supported implementation path:
   - Packaged C# desktop provider that implements Microsoft.Windows.Widgets.Providers.IWidgetProvider.
   - Packaged C++/WinRT desktop provider that implements IWidgetProvider.
   - PWA widget defined in the web app manifest and handled by its service worker.
   If the request doesn't contain enough information to select a path, ask before creating files.
   Don't mix the PWA service-worker model with the desktop COM provider model.
   Apply desktop-specific API, package, and lifecycle requirements below only to desktop providers.
   For a PWA, use the web app manifest, service-worker, testing, and publishing guidance at:
   https://learn.microsoft.com/microsoft-edge/progressive-web-apps/how-to/widgets

2. For a desktop provider:
   - Use a currently supported stable Windows App SDK release. Verify the package and API names
     against current Microsoft Learn documentation instead of inventing a version.
   - Require package identity. Register the out-of-process COM server and
     com.microsoft.windows.widgets app extension in Package.appxmanifest.
   - Generate one CLSID and use the same value in the provider class, COM factory registration,
     com:Class element, and WidgetProvider/CreateInstance element.
   - Implement CreateWidget, DeleteWidget, OnActionInvoked, OnWidgetContextChanged, Activate,
     and Deactivate.
   - Treat WidgetContext.DefinitionId as the manifest definition and WidgetContext.Id as the
     individual pinned instance. Store and restore state per instance.
   - On process startup, call WidgetManager.GetDefault().GetWidgetInfos() and restore pinned
     instances from CustomState. Make creation and recovery idempotent.
   - Synchronize shared state because provider callbacks can run concurrently.
   - Don't retain callback argument objects after a callback returns.
   - For C# only: follow the documented class-factory pattern. In IClassFactory.CreateInstance,
     obtain a temporary pointer with MarshalInspectable<IWidgetProvider>.FromManaged(new T()),
     query the requested interface with Marshal.QueryInterface, and release the temporary
     pointer in finally. Return HRESULTs at the COM boundary. Use a Windows application output
     type (WinExe) for the final experience so COM activation doesn't open a console window.
   - If the widget is customizable, set IsCustomizable="true" in the widget manifest, implement
     IWidgetProvider2.OnCustomizationRequested, and render a separate customization card. Read
     Adaptive Card input values from WidgetActionInvokedArgs.Data, validate them, and persist
     the resulting settings per widget. Confirm that the COM-callable wrapper exposes every
     provider interface that the class implements.
   - For C++/WinRT: use the walkthrough's non-caching winrt::no_module_lock class factory,
     serialize provider construction, query the requested interface, and translate exceptions
     to HRESULTs at the COM boundary.
   - Send logging to an app-controlled log or debugger output.
   - Target explicit architectures such as x64 and ARM64. Don't use AnyCPU.

3. Select the content model:
   - For an Adaptive Card widget, create a JSON template and a separate JSON data payload.
     Serialize values used as TextBlock text as strings, including numeric counts.
   - For a desktop HTML widget, use the documented web-widget metadata.webUrl payload, provide an
     Adaptive Card fallback, and add IWidgetResourceProvider or IWidgetProviderMessage only
     when the requested scenario needs those APIs.
     Web widgets are available only to users in the European Economic Area (EEA).
     Check regional and host requirements before selecting this path.
   - For a PWA, follow the PWA widget manifest and service-worker documentation instead of
     generating desktop IWidgetProvider code.

4. Implement interaction safely:
   - For a desktop provider, handle Action.Execute in OnActionInvoked. For a PWA, handle it
     through the service worker's widgetclick event.
   - Display Action.Execute only when $host.isUserContextAuthenticated is true.
   - Use Action.OpenUrl for navigation and for an interaction that must remain available when
     the widget user context isn't authenticated.
   - Validate every action verb and input before changing state.
   - Don't put secrets, access tokens, or credentials in the Adaptive Card payload or custom state.

5. Implement responsive and fallback content:
   - For a desktop provider, declare every supported size in Package.appxmanifest.
   - Use $host.widgetSize, $host.hostTheme, and other documented $host properties when needed.
   - Design the small layout separately; don't assume a medium layout will fit.
   - Don't rely on scrolling to reach the widget's primary information. Bound configurable
     collections, and verify that every configured item remains visible in the largest supported
     size. Prefer compact, item-specific links over broad summary links when users need to act
     on individual items.
   - Provide explicit loading, unavailable, offline, and signed-out states that are relevant
     to the requested widget.
   - For a desktop provider, set WidgetUpdateRequestOptions.IsPlaceholderContent when the
     payload isn't yet personalized or actionable.
   - Include accessible display names, descriptions, icon assets, screenshot assets, and
     screenshot alternative text for the widget picker.

6. Keep capabilities and dependencies minimal:
   - Add only the package capabilities required by the widget and its data source.
   - Use HTTPS for remote content.
   - Don't add broad file-system, account, network, or restricted capabilities without a
     requirement and an explanation.

7. Build and deploy:
   - Follow the repository's existing build and packaging structure.
   - For a PWA, follow the PWA widget documentation to test from a public endpoint and package
     with PWABuilder when targeting the Microsoft Store. Don't generate a desktop COM server.
     The Windows App SDK, COM registration, and CLI-first C# steps below are desktop-specific.
   - For a desktop provider, prefer the specific Windows App SDK runtime and widget component
     packages required by the provider over an umbrella dependency when producing a small
     framework-dependent package.
   - Reuse a stable development certificate for local upgrade testing. Don't overwrite a trusted
     certificate on every build. Never publish a private key, PFX, certificate password, token,
     or other secret in source control or release assets.
   - If a public installer trusts a self-signed development certificate, pin the expected public
     certificate thumbprint, verify that it is an unexpired non-CA certificate restricted to code
     signing, and confirm that it signed the MSIX before requesting trust. With explicit user
     consent, install only the public certificate in **Trusted People**. Never add an end-entity
     development certificate to **Trusted Root Certification Authorities**.
   - Increment the package version whenever installing changed MSIX contents. Windows rejects a
     changed package with the same identity and version.
   - The Windows App Development CLI is in public preview. Features and commands may change;
     check the installed version's help before using it.
   - For a CLI-first single-project MSIX C# provider, use EnableMsixTooling=true, keep
     Package.appxmanifest in the provider project, and register a development package with:
       winapp run <project>.csproj --configuration Release --arch x64 --no-launch
     This command registers the package without launching the app. It doesn't verify
     activation or rendering in the Widgets Board.
   - Don't try to replace a development-registered package with an MSIX that uses the same
     identity. Unregister the development package before testing the packaged deployment.
   - Fix build, manifest, registration, and architecture errors before continuing.
   - For a desktop provider, confirm that the registered package contains the windows.comServer
     extension and the com.microsoft.windows.widgets app extension.

8. Validate in the real Widgets Board:
   - Open the board, open the widget picker, and confirm the provider name, widget definition,
     icon, screenshot, and description.
   - Pin the widget and verify the initial template and data.
   - Resize it to every supported size and check for clipping, overlap, overflow, excess empty
     space, and incorrect conditional content.
   - Test every available action and verify the updated data and persisted per-widget settings.
     For desktop providers, verify CustomState.
   - If a desktop widget is customizable, open **Customize widget**, test invalid input, Save,
     and Cancel, and verify that saved settings refresh immediately and survive a host restart.
   - Open item-specific links and verify that each one targets the expected resource rather
     than a broad organization or product page.
   - For a desktop provider, restart the provider process and verify that pinned widget state
     is restored. For a PWA, verify restoration when the service worker activates again.
   - Unpin the widget and verify DeleteWidget for a desktop provider or the widgetuninstall
     service-worker event for a PWA.
   - Don't report interaction success from the Adaptive Cards Designer; it doesn't provide
     Windows $host values or invoke provider callbacks.
   - If the host reports an unauthenticated user context, verify the fallback and clearly
     report that Action.Execute couldn't be exercised in that session.

9. Finish with:
   - A concise list of files created or changed.
   - The selected widget architecture and why it matches the request.
   - Build and deployment results.
   - Observed Widgets Board test results for discovery, rendering, sizes, actions, restart
     persistence, and unpinning. Separate these from "Manual verification required", which
     must list every unperformed check with exact steps and expected results.
   - Any host, account, SDK, or OS limitation that prevented a requested test.

Don't stop after generating snippets. Deliver a buildable implementation and perform the
available validation. Don't invent Windows widget APIs, manifest elements, host properties,
or supported behavior.

생성된 위젯을 검토

결과를 게시하기 전에 다음 영역을 검토합니다.

• 앱은 올바른 위젯 공급자 아키텍처를 사용하며 호환되지 않는 데스크톱 및 PWA 패턴을 결합하지 않습니다.
• 데스크톱 공급자 등록은 위젯 공급자 패키지 매니페스트 형식을 따릅니다.
• 템플릿은 문서화된 Windows 위젯 호스트 속성만 사용합니다.
• 위젯은 지원되지 않는 작업을 표시하지 않고 인증되지 않은 상태, 사용할 수 없음 및 자리 표시자 상태를 처리합니다.
• 지원되는 모든 크기는 위젯 보드에서 렌더링되고 시각적으로 확인되었습니다.
• 데스크톱 공급자는 다시 시작한 후 사용자 지정 상태를 복원하고 동시 콜백을 안전하게 처리하거나 서비스 작업자가 활성화될 때 PWA가 위젯을 복원합니다.
• 최종 앱은 해당 시나리오에 필요한 기능 및 종속성만 사용합니다.

AI 생성 코드를 검토하는 방법에 대한 광범위한 지침은 Windows 개발을 위한 보안 및 책임 있는 AI를 참조하세요.